Hopsule MCP: Making AI Agents Decision-Aware

Introduction to Decision-Aware AI

In the modern engineering landscape, AI agents have become indispensable partners in the development lifecycle. However, most AI tools operate in a vacuum, lacking the vital organizational judgment and historical context that define a team's unique engineering culture. Hopsule MCP (Model Context Protocol) bridges this gap by serving as a dedicated bridge between your team's collective memory and the AI agents you use every day. By connecting tools like Cursor and Claude to Hopsule, you transform generic language models into context-aware collaborators that respect your established decisions and understand the reasoning behind your architecture.

The Model Context Protocol is an open standard that enables seamless integration between data sources and AI applications. Hopsule's implementation of this protocol ensures that your Decisions, Memories, and Context Packs are no longer siloed within a dashboard but are actively enforced and referenced during the coding process. This integration ensures that when an AI agent suggests a code change or explains a system component, it does so with full awareness of the constraints and commitments your team has formally accepted.

Important: Hopsule MCP provides read-only access to your organizational memory. While AI agents can query and understand your decisions, they lack the authority to create, modify, or deprecate them. This design choice preserves the principle that humans remain the ultimate authority in the decision-making process, while AI serves as an informed advisory layer.

The Value of Context Preservation in AI Workflows

Engineering organizations often suffer from "organizational amnesia," where the reasoning behind critical technical choices is lost as teams scale or personnel change. When AI agents are introduced into these environments without a memory layer, they frequently suggest patterns that contradict established standards or reintroduce bugs that were previously solved. Hopsule MCP solves this by providing a persistent, append-only context stream that informs every interaction. By surfacing Memories—the "why" behind the "what"—AI agents can provide more nuanced suggestions that align with long-term project goals rather than just immediate syntax requirements.

Furthermore, the use of Context Packs (also known as Capsules) allows teams to bundle specific decisions and memories for different domains. Through the MCP interface, an AI agent can dynamically request the relevant Capsule for a specific task, ensuring it has the right governance framework for the job at hand. This portability is central to the Hopsule philosophy: your engineering judgment should follow the work, regardless of which tool or environment is being used. Whether a developer is working in a terminal via the Hopsule CLI or refactoring a complex module in an IDE, the same authoritative context remains available.

Supported AI Agents and Environments

Hopsule MCP is designed to be highly compatible with the growing ecosystem of MCP-enabled tools. Because it follows the standardized protocol, it can be integrated into any environment that supports external context servers. Currently, the most common use cases include:

• Cursor: Enhance your AI-native IDE experience by allowing Cursor to index your Accepted Decisions. This prevents the IDE from suggesting code that violates your team's architectural constraints.

• Claude Desktop: Use the Claude interface as a powerful research tool that can query your Knowledge Graph to explain complex system histories or find the reasoning behind specific technical debt.

• Custom AI Agents: Any agent built on the Model Context Protocol can connect to the Hopsule MCP server to gain immediate access to your team's governance layer.

• Hopsule for VS Code: While the IDE extension provides native enforcement, the MCP server adds an additional layer of depth for the built-in AI chat functionalities.

Tip: For the best experience, we recommend using Hopsule MCP alongside the Hopsule Dashboard. While the MCP server provides the context to your AI, the Dashboard remains the primary interface for visualizing your Brain (Knowledge Graph) and managing the lifecycle of your decisions.

Core Architectural Principles: Read-Only Governance

A fundamental tenet of the Hopsule ecosystem is that enforcement is remembrance, not control. This philosophy is strictly applied to the MCP implementation. The Hopsule MCP server is built with a read-only architecture. This means that an AI agent, no matter how sophisticated, can never "accidentally" accept a draft decision or deprecate an existing one. All mutations to your organizational memory must occur through the Hopsule Dashboard, the Hopsule CLI, or direct human interaction with Hopper.

By restricting the AI to a read-only role, Hopsule ensures that the integrity of your Decisions remains intact. The AI acts as a highly efficient librarian and advisor, capable of searching through thousands of Memories in milliseconds to find the one relevant piece of context that prevents a regression. This separation of powers ensures that the team maintains full authority over the governance layer while reaping the productivity benefits of context-aware AI assistance.

Setup and Configuration Guide

Integrating Hopsule MCP into your workflow requires a few simple configuration steps. Before beginning, ensure you have an active Hopsule account and have generated an Access Token from the Hopsule Dashboard settings page. This token is required to authenticate the MCP server with your organization's encrypted memory store.

1. Generate an Access Token: Navigate to the Hopsule Dashboard, go to Settings, and select API & Integration. Create a new token with the "Read-Only" scope specifically for MCP usage.

2. Install the Hopsule MCP Server: Depending on your environment, you can point your MCP client to the Hopsule server executable. If you are using the Hopsule CLI, the MCP server is often bundled as a sub-command.

3. Configure the Client: In your AI agent's configuration file (e.g., claude_desktop_config.json or Cursor's MCP settings), add the Hopsule entry. You will need to provide the command to run the server and include your HOPSULE_API_KEY as an environment variable.

4. Select Your Project Context: You can restrict the MCP server to specific projects by providing a PROJECT_ID. This ensures the AI agent only sees Decisions and Memories relevant to the current codebase.

5. Verify the Connection: Once configured, restart your AI agent. You should see "Hopsule" listed as an active context provider. You can test the connection by asking the agent: "What are the most recent accepted decisions for this project?"

Important: Never share your Access Token or commit it to version control. Hopsule uses end-to-end encryption, and your token is the key to accessing your team's preserved context. Treat it with the same level of security as a production database credential.

Reference: Available MCP Tools and Resources

The Hopsule MCP server exposes several tools that AI agents use to navigate your organizational memory. Understanding these tools helps you prompt your AI more effectively. The following table describes the primary capabilities available to your AI agents:

These tools allow the AI to traverse your Knowledge Graph efficiently. For example, when an AI agent uses search_memory, it isn't just looking for keywords; it is looking for the organizational judgment that matches the developer's current intent. This results in suggestions that are not only syntactically correct but also strategically aligned with the team's goals.

Example Workflows and AI Conversations

To maximize the utility of Hopsule MCP, developers should treat the AI agent as a junior partner who has access to the team's most senior wisdom. By explicitly asking the AI to check Hopsule, you can ensure high-quality, decision-aligned output. Below are several common workflows where the MCP integration excels.

Architectural Alignment during Refactoring

When refactoring a legacy module, a developer might prompt Cursor: "Refactor this function to use our standard error handling pattern, checking Hopsule for any relevant decisions." The AI agent will then invoke list_decisions, identify a decision titled "Standardized Result-Type Error Handling," and apply that specific pattern to the code. This eliminates the need for the developer to manually find the documentation or for a reviewer to point out the inconsistency later.

Onboarding and Context Discovery

A new engineer joining a project can use Claude Desktop with the Hopsule MCP to ask: "What is the history of our choice to use a NoSQL database for the activity feed?" The agent will use list_memories and get_decision to reconstruct the reasoning from eighteen months ago, citing the specific Memories that led to that choice. This turns the AI into an automated onboarding assistant that preserves the remembrance of the founding team.

Conflict Detection and Resolution

If a developer asks an AI agent to implement a feature that contradicts an Accepted Decision, the context-aware agent can flag the contradiction immediately. For example: "I want to add a direct database connection here." The AI, seeing a decision that mandates "All database access must go through the Repository Layer," can respond: "I can help with that, but please note that Decision #42 requires using the Repository Layer. Should we follow that pattern instead?" This is the essence of enforcement as remembrance.

Security, Encryption, and Data Sovereignty

At Hopsule, security is not a premium feature; it is a baseline guarantee. Hopsule MCP benefits from the same rigorous security standards as the rest of our platform. All data transmitted between your environment and the Hopsule servers is protected by TLS 1.3, and all data at rest is encrypted using AES-256. Because Hopsule is decision-first, we prioritize the integrity and confidentiality of your organizational judgment above all else.

For organizations with strict compliance requirements, the Hopsule Enterprise (Self-Hosted) option allows you to run the entire Hopsule stack, including the MCP backend, within your own infrastructure. In this configuration, your Decisions and Memories never leave your controlled environment. Even in our cloud-hosted version, Hopsule for VS Code and the MCP server are designed to process as much as possible locally, ensuring that your sensitive source code is never sent to Hopsule servers—only the metadata required to provide context is exchanged.

Tip: You can audit all MCP-related queries through the Activity Feed in the Hopsule Dashboard. This provides a transparent record of which AI agents accessed which decisions, ensuring full traceability for compliance and security auditing.

Usage Guidelines and Rate Limiting

To ensure optimal performance for all users, Hopsule MCP is subject to usage guidelines based on your plan tier. While we encourage active use of the context layer, the MCP server is optimized for high-efficiency queries rather than bulk data exports. AI agents are programmed to be "polite" consumers of the API, fetching only the context necessary for the current conversation window.

• Free Tier: Standard rate limits apply, suitable for solo developers and small projects.

• Pro Tier: Increased limits for larger teams and more frequent AI interactions.

• Enterprise Tier: Custom rate limits and priority access to the Hopsule API.

If an AI agent exceeds the rate limit, the MCP server will return a standard error code, and the agent will typically notify the user to wait a few moments. You can monitor your organization's usage statistics directly within the Hopsule Dashboard under the Usage & Billing section.

Troubleshooting Connection and Context Issues

If your AI agent is unable to see your Hopsule context, follow these troubleshooting steps to resolve the issue:

1. Check Token Validity: Ensure your Access Token hasn't expired or been revoked. You can test the token using a simple curl command to the Hopsule API.

2. Verify Project ID: If you have restricted the MCP server to a specific PROJECT_ID, ensure that the decisions you are looking for are actually tagged with that project in the Hopsule Dashboard.

3. Update the MCP Server: We frequently release updates to Hopsule MCP to support new protocol features and improve semantic search accuracy. Ensure you are running the latest version via the Hopsule CLI.

4. Inspect Client Logs: Tools like Claude Desktop and Cursor provide logs for their MCP connections. Check these logs for any "Connection Refused" or "Authentication Failed" messages.

5. Confirm Decision State: By default, some tools only fetch Accepted Decisions. If your decision is still in the Draft or Pending state, it may not appear in general AI queries unless specifically requested.

For further assistance, please refer to the Hopsule Dashboard help center or contact our support team. We are committed to ensuring that your team's memory is always available whenever and wherever you choose to build.

Conclusion: The Future of Decision-Aware Engineering

The integration of Hopsule MCP into your development workflow represents a fundamental shift in how AI is utilized in engineering. By moving away from generic code generation and toward decision-aware assistance, teams can maintain a higher standard of quality and consistency. Hopsule ensures that your most important commitments—your Decisions—are never forgotten, and your most valuable insights—your Memories—are always at the fingertips of every developer and every AI agent. As you continue to build, Hopsule will be there to remember, so you can focus on making the next great decision.