What Is Hopsule MCP? Connecting AI Agents to Your Decisions

Introduction

Hopsule MCP is the definitive bridge between your organization’s collective memory and the AI agents your team uses every day. This article provides a comprehensive guide on how to connect AI agents, such as Cursor and Claude, to your team’s accepted decisions and historical context, ensuring that every AI-generated suggestion is grounded in established organizational judgment. By the end of this guide, you will understand how to transform a standard AI agent into a decision-aware partner that respects the governance and preservation standards of your engineering organization.

The philosophy of Hopsule is rooted in the belief that enforcement is remembrance, not control. When an AI agent has access to Hopsule MCP, it doesn’t just guess based on generic training data; it remembers the specific commitments your team has made. This prevents context drift and ensures that the reasoning behind every architectural choice is available to the agent at the moment of creation. Whether you are a solo developer or part of a global enterprise, Hopsule MCP provides the necessary authority to keep your AI sessions aligned with your project’s unique trajectory.

Prerequisites

Before connecting an AI agent to Hopsule MCP, ensure you have completed the following requirements:

• An active Hopsule account with at least one Project created.

• Administrative or Member access to the Project you wish to expose via MCP.

• A set of Accepted Decisions within the Hopsule Dashboard (Draft or Pending decisions are not exposed via MCP to maintain governance).

• A compatible AI client that supports the Model Context Protocol (e.g., Cursor, Claude Desktop, or any agent using the Hopsule API).

• A valid Hopsule API Token, which can be generated from the Settings section of the Hopsule Dashboard.

Understanding the Role of Hopsule MCP

Hopsule MCP is not a simple data connector; it is a specialized gateway for organizational context. Unlike generic integrations that might attempt to store information or save notes, Hopsule MCP provides a structured, read-only stream of Decisions, Memories, and Context Packs. This distinction is critical for maintaining the integrity of your engineering governance.

Decisions as Enforceable Constraints

In the Hopsule ecosystem, a Decision is an explicit commitment. When an AI agent connects via Hopsule MCP, it receives these decisions as enforceable constraints. If a decision states that "All internal APIs must use gRPC," the agent will be aware of this rule and can warn the developer or adjust its code generation accordingly. This is the essence of preservation: ensuring that past agreements dictate future actions.

Memories as Persistent Reasoning

While Decisions tell the agent what to do, Memories explain why. Memories are append-only context entries that capture the history and lessons learned during the decision-making process. Hopsule MCP allows agents to query these memories to understand the nuances of a project, preventing the repetition of past mistakes and providing a deeper level of insight than standard documentation could ever offer.

Context Packs (Capsules) for Portability

Context Packs, or Capsules, allow you to bundle specific sets of Decisions and Memories. Through Hopsule MCP, you can instruct an AI agent to focus on a specific Capsule. This is particularly useful for multi-repo environments or specialized teams where an agent needs the context of a "Security Capsule" or a "Frontend Standards Capsule" without being overwhelmed by irrelevant data.

Step-by-Step: Setting Up Hopsule MCP

Connecting your AI agents to Hopsule requires a few precise steps within the Hopsule Dashboard and your local environment. Follow these instructions to establish a secure, encrypted connection.

Step 1: Generate an API Token

1. Log in to the Hopsule Dashboard.

2. Navigate to the Settings menu in the sidebar.

3. Select the API Keys tab.

4. Click the Generate New Token button.

5. Provide a descriptive name for the token (e.g., "Cursor-Integration-Primary").

6. Select the appropriate Project scope. You can grant access to all projects or limit the token to a specific organizational unit.

7. Copy the token immediately. For security reasons, Hopsule uses end-to-end encryption, and this token will not be displayed again.

Step 2: Configure Hopsule MCP for Cursor

Cursor is a popular AI-native IDE that integrates deeply with Hopsule MCP to provide inline decision enforcement.

1. Open the Cursor settings by clicking the gear icon or using the keyboard shortcut.

2. Navigate to the Models or Features section and locate the MCP settings.

3. Click Add New MCP Server.

4. In the Name field, enter Hopsule.

5. In the Type dropdown, select command or stdio depending on your local setup.

6. In the Command field, enter the path to the Hopsule CLI or the direct MCP execution command provided in the Hopsule Dashboard integration page.

7. Include your API Token as an environment variable or argument as specified in the dashboard instructions.

8. Click Save. Cursor will now attempt to initialize the connection.

Step 3: Configure Hopsule MCP for Claude Desktop

To use Hopsule context within the Claude Desktop application, you must modify your local configuration file.

1. Locate your Claude Desktop configuration file (usually found in ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or the equivalent path on Windows).

2. Add a new entry under the mcpServers key.

3. Name the entry hopsule.

4. Set the command to the execution path of the Hopsule MCP connector.

5. Add an env object containing your HOPSULE_API_TOKEN.

6. Restart the Claude Desktop application. You should see a hammer icon or a Hopsule logo indicating that the agent is now decision-aware.

Step 4: Verifying the Connection

1. Once configured, ask your AI agent a question about your team's standards. For example: "What are our current decisions regarding database migrations?"

2. The agent should respond by referencing specific Decisions found in your Hopsule Dashboard.

3. Check the Activity Feed in the Hopsule Dashboard to see a log of the MCP access (this provides an audit trail for governance).

Managing Context via the Knowledge Graph

One of the most powerful features of Hopsule is the Knowledge Graph (also referred to as the Brain). When using Hopsule MCP, AI agents can navigate this graph to see how decisions are linked. For example, if a decision about "Authentication" is linked to a memory about a "2023 Security Audit," the AI agent can traverse this relationship to provide a more nuanced answer.

To optimize the agent's performance, ensure that you are actively linking related Decisions and Memories in the Hopsule Dashboard. Use the Knowledge Graph view to identify orphaned decisions that lack context. By strengthening these links, you improve the quality of the context provided through Hopsule MCP.

Security and Data Sovereignty

Hopsule is designed with a "Security First" mindset. All data transmitted via Hopsule MCP is protected by TLS 1.3 in transit and AES-256 at rest. For organizations using Hopsule Enterprise (Self-Hosted), the MCP traffic never leaves your internal network, ensuring total data sovereignty.

Hopsule MCP operates on a strict read-only basis. While an AI agent can read your decisions and memories to provide context, it can never mutate, delete, or create new decisions autonomously. This ensures that humans remain the sole authority for organizational judgment. If an agent suggests a new decision, it must be drafted and accepted by a team member via the Hopsule Dashboard or Hopsule CLI before it becomes part of the enforceable memory layer.

Tips and Best Practices

• Use Descriptive Memory Titles: Since AI agents use these titles to index context, clear and concise naming helps the agent find relevant information faster.

• Leverage Context Packs: Instead of giving an agent access to every decision in the organization, create specialized Capsules for specific projects to reduce noise and improve focus.

• Regularly Deprecate Decisions: To prevent the AI agent from following outdated rules, use the Deprecate function in the Hopsule Dashboard for decisions that are no longer valid.

• Monitor Hopper Suggestions: Use Hopper, the built-in assistant, to review how your decisions are being interpreted before deploying them to external agents via MCP.

• Audit Your API Tokens: Periodically rotate your tokens in the Settings panel to maintain a high security posture.

• Utilize the Brain View: Regularly check the Knowledge Graph to ensure your decisions and memories are well-connected, which directly improves MCP context quality.

Troubleshooting

If you encounter issues while setting up or using Hopsule MCP, consult the table below for common causes and solutions.

Related Articles

• Managing Context Packs: How to Bundle Decisions and Memories

• The Decision Lifecycle: From Draft to Accepted

• Using the Knowledge Graph to Visualize Organizational Memory

• Setting Up Hopsule for VS Code and Cursor

By integrating Hopsule MCP into your workflow, you are moving beyond simple documentation and into the realm of active context preservation. Your AI agents are no longer just tools; they are informed participants in your team's ongoing journey of remembrance and governance. For further assistance, please contact your organization's Hopsule administrator or visit the community forum.