Model Context Protocol (MCP)
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) integration in Cogmo provides a long-lived client layer that allows users to add third-party MCP servers (such as GitHub, Gmail, or Slack) to the agent's capabilities. It exposes these external tools through a unified McpRegistry facade, allowing the agent to utilize them alongside native tools while maintaining strict boundaries for security and performance.
Sources: design/integrations/mcp.md:5-10, changelog.d/2026-05-04-mcp-integration-design-doc-phase.md
Architecture Overview
The MCP system is organized into a modular structure under src/mcp/, consisting of a persistent store, a connection pool for lazy-loading subprocesses, and adapters that translate MCP tool descriptors into Cogmo's internal ToolSpec format. The orchestrator interacts solely with the McpRegistry interface, ensuring that MCP-specific logic and SDK dependencies do not leak into the core agent loop.
Component Structure
| Component | Responsibility |
|---|---|
| McpStore | Manages persistent server configurations and tool schema pins in the database. |
| McpRegistry | The primary facade for the orchestrator to resolve tools and perform admin operations. |
| McpConnectionPool | Manages a process-scoped pool of server connections with idle eviction and lazy-loading. |
| McpToolAdapter | Adapts MCP callTool results and descriptors into Cogmo's standard ToolSpec. |
| McpConnection | A thin wrapper over the MCP SDK Client, decoupling the system from the specific library implementation. |
Sources: design/integrations/mcp.md:27-41, changelog.d/2026-05-04-mcp-client-pool-adapter-registry.md
Logic Flow: Tool Resolution
The following diagram illustrates how MCP tools are merged into the agent's available toolset during a conversation turn.
The resolveTools process ensures that only approved tools matching the profile's glob filters (e.g., mcp__github__*) are exposed to the agent, respecting a hard budget (default 25) to prevent LLM performance degradation.
Sources: design/integrations/mcp.md:143-149, changelog.d/2026-05-04-mcp-orchestrator-wiring-admin-commands.md
Data Model and Security
Database Tables
The system uses two primary tables to manage MCP state and protect against "schema rug-pull" attacks.
| Table | Purpose | Key Fields |
|---|---|---|
mcp_servers | Stores server metadata and transport config. | id, name, config (JSONB), approvalStatus |
mcp_server_tools | Pins tool schemas to detect unexpected changes. | serverId, toolName, schemaHash, approvalStatus |
Sources: design/integrations/mcp.md:65-98, changelog.d/2026-05-04-mcp-integration-design-doc-phase.md
Trust Model and Schema Pinning
Cogmo implements a strict security model for MCP:
- Trust Allowlist: Servers are treated as
untrustedby default unless explicitly listed in a code-level allowlist. - Schema Pinning: The system hashes tool schemas (SHA256). If a server changes a tool's input schema or description without re-approval, the tool is marked as
needs_reapprovaland tool calls are blocked. - Sandboxing: Untrusted stdio servers are planned to run within
sysboxcontainers with restricted filesystem and network access.
Sources: design/integrations/mcp.md:188-210, changelog.d/2026-05-04-mcp-client-pool-adapter-registry.md
Lifecycle and Connection Management
Lazy Connection Establishment
Connections to MCP servers are lazy-loaded. The subprocess is only spawned when the agent first attempts to call a tool from that specific server.
Failure Handling and Eviction
- Timeouts: A default 30s timeout is enforced for all tool calls.
- Idle Eviction: Connections that remain idle for more than 10 minutes are automatically torn down to conserve resources.
- Auto-Reconnect: The system implements a "reconnect-once" policy. If a transport closes, the pool attempts one reconnection on the next call before marking the server as unhealthy.
Sources: design/integrations/mcp.md:168-185, changelog.d/2026-05-04-mcp-client-pool-adapter-registry.md
Administrative Interface
Users manage MCP servers through a Telegram-based admin interface using the /mcp command.
| Command | Action |
|---|---|
/mcp add <name> <json> | Registers a new server with the provided configuration. |
/mcp approve <server> | Connects to a server and pins its tools for review. |
/mcp approve <server> <tool> | Approves a specific tool for use by the agent. |
/mcp list | Lists all configured servers and their current status. |
/mcp pending | Shows servers that require re-approval due to schema changes. |
Sources: changelog.d/2026-05-04-mcp-orchestrator-wiring-admin-commands.md
Conclusion
The MCP integration enables Cogmo to scale its capabilities via a standardized protocol while maintaining the security and performance standards required for a personal agent. By utilizing lazy-loading, schema pinning, and per-profile tool filtering, the system ensures that third-party integrations are both powerful and safe.