Model Context Protocol (MCP)
Relevant source files
The following files were used as context for generating this wiki page:
- packages/coding-agent/DEVELOPMENT.md
- packages/coding-agent/src/internal-urls/mcp-protocol.ts
- packages/coding-agent/src/prompts/system/system-prompt.md
- packages/coding-agent/src/discovery/helpers.ts
- packages/ai/src/providers/devin/proto/exa/codeium_common_pb/codeium_common.proto
- packages/coding-agent/src/prompts/agents/librarian.md
The Model Context Protocol (MCP) in the Oh My Pi project is a standardized communication layer that enables AI agents to interact with external tools, resources, and servers. It serves as a bridge between the core agent logic and external integrations, such as SaaS APIs, databases, or local services, providing a unified way for models to discover and consume context beyond the immediate codebase.
MCP is integrated into the system-level prompts and tool discovery mechanisms, allowing agents to fetch data via mcp:// URLs and execute tools provided by MCP servers. This protocol ensures that external capabilities are seamlessly presented to the model as part of its available toolset or internal resource registry.
Sources: packages/coding-agent/DEVELOPMENT.md:57, packages/coding-agent/src/prompts/system/system-prompt.md:65-71
Architecture and Components
The MCP implementation follows a manager-client architecture where a central MCPManager coordinates multiple connected servers and their respective resources.
MCP Manager and Server Discovery
The MCPManager is responsible for tracking connected servers and their capabilities. In the TUI and CLI environments, MCP servers are discoverable at session start. If a task requires external integrations not found in local tools, the agent is directed to use discovery tools to locate relevant MCP servers.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:83-88, packages/coding-agent/src/internal-urls/mcp-protocol.ts:84-86
Internal URL Resolution
The system utilizes a custom protocol handler, McpProtocolHandler, to resolve mcp:// URLs. These URLs allow agents to read specific resources from connected servers using a template-matching logic.
The diagram shows how an internal MCP URL is resolved to a specific server and resource.
Sources: packages/coding-agent/src/internal-urls/mcp-protocol.ts:84-135
Resource Resolution Logic
MCP resources are identified by URIs. Since multiple servers might exist, the system employs a scoring mechanism to find the best match for a given URI against literal URIs or URI templates.
URI Template Matching
When a specific literal URI match is not found, the system evaluates URI templates (e.g., test://notes/{id}). The matching algorithm scores templates based on:
- Literal Characters: The count of non-placeholder characters (higher is better).
- Expression Count: The number of placeholders (lower is better for ties).
- Server Order: The index of the server in the connection list.
Sources: packages/coding-agent/src/internal-urls/mcp-protocol.ts:10-25, packages/coding-agent/src/internal-urls/mcp-protocol.ts:50-75
Configuration and Management
MCP servers can be configured at both the user and project levels. This allows for global integrations as well as project-specific tools.
Server Configurations
MCP servers are defined as either local (executable commands) or remote (endpoint URLs).
| Field | Type | Description |
|---|---|---|
command | string | The binary or script to execute (Local only). |
args | string[] | Arguments passed to the command (Local only). |
env | Map | Environment variables for the process (Local only). |
url | string | Endpoint for remote MCP servers (Remote only). |
headers | Map | Authentication or custom headers (Remote only). |
Sources: packages/ai/src/providers/devin/proto/exa/codeium_common_pb/codeium_common.proto:1159-1175
Registry and Discovery Pathing
The system scans specific directories and configuration files to initialize the MCP ecosystem:
- User Registry:
~/.omp/plugins/installed_plugins.json - Project Registry:
.omp/plugins/installed_plugins.json(walked up from CWD). - External Links: Support for linked extension directories that provide MCP capabilities.
Sources: packages/coding-agent/src/discovery/helpers.ts:544-555, packages/coding-agent/src/discovery/helpers.ts:586-595
Protocol Operations
The following table summarizes the key data structures and operations within the MCP implementation.
| Component | Description | Reference |
|---|---|---|
mcp:// | Protocol for accessing external resources as if they were local files. | mcp-protocol.ts |
MCPManager | Singleton managing lifecycle and communication with all MCP servers. | mcp/manager.ts |
McpPromptScopeItem | Data structure for passing MCP-based prompts to agents. | codeium_common.proto |
McpResourceItem | metadata for a specific resource including URI, mime type, and server name. | codeium_common.proto |
Sources: packages/coding-agent/src/internal-urls/mcp-protocol.ts:84, packages/ai/src/providers/devin/proto/exa/codeium_common_pb/codeium_common.proto:1062-1076
Tool Execution Flow
Agents use MCP tools when native tools are insufficient. The model context is updated with mcpDiscoveryMode to alert the agent of discoverable servers.
This diagram illustrates the flow of tool discovery and execution via the MCP layer.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:83-88, packages/coding-agent/DEVELOPMENT.md:57
Conclusion
The Model Context Protocol (MCP) is a critical extensibility feature of Oh My Pi, enabling a "plug-and-play" architecture for external tools and resources. By standardizing how servers describe their resources via URIs and how tools are invoked, MCP allows agents to perform complex, cross-platform tasks (such as interacting with databases or web services) while maintaining a consistent internal interface based on URI resolution and structured tool calls.
Sources: packages/coding-agent/DEVELOPMENT.md:143-145, packages/coding-agent/src/prompts/agents/librarian.md:75-80