Model Context Protocol (MCP)
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) in the pi-digby project facilitates the integration of external tools and data sources into the agent's capabilities. It acts as a bridge between the core agent logic and external MCP servers, such as Exa search, allowing the agent to perform complex tasks like web searching or interacting with external APIs via a standardized interface.
In pi-digby, MCP is implemented using the pi-mcp-adapter package. This adapter is dynamically loaded and injected into the agent's runtime environment through the extensionFactories configuration during the setup of the AgentSession. This allows the agent to discover and execute tools provided by configured MCP servers.
Sources: CLAUDE.md:15, src/agent/setup.ts:145-160
Architecture and Integration
The MCP system is integrated into the AgentSession as a runtime extension. It leverages a dynamic loading mechanism to incorporate the pi-mcp-adapter without requiring pre-compilation of the adapter's TypeScript source.
Component Overview
| Component | Description |
|---|---|
pi-mcp-adapter | The core integration package that translates between the agent's tool calls and MCP server protocols. |
mcp.json | The configuration file defining the available MCP servers and their connection parameters. |
ResourceLoader | Handles the loading and reloading of extensions, including the MCP adapter, during the agent's lifecycle. |
AgentSession | The primary orchestrator that binds the MCP extensions to the active agent run. |
Sources: src/agent/setup.ts:133-143, src/agent/setup.ts:175-185, CLAUDE.md:52
Initialization Flow
The following diagram illustrates how the MCP adapter is loaded and bound to the agent session during the setup phase.
The diagram shows the sequential process of using jiti to import the TypeScript adapter and registering it as an extension factory.
Sources: src/agent/setup.ts:136-160, src/agent/setup.ts:193-194
Configuration and Persistence
MCP servers are configured via a JSON file, and their settings are persisted across container restarts to ensure continuity of service.
Configuration Management
The primary configuration file is located at .pi/mcp.json within the working directory. This file defines the servers and placeholders for sensitive credentials, such as the EXA_API_KEY.
- Seed Config: On the first run, the system seeds the configuration from a repository default if one does not exist on the persistent storage.
- Environment Variable Substitution: The
entrypoint.shscript performssedoperations to replace placeholders (e.g.,EXA_API_KEY_PLACEHOLDER) with actual secrets retrieved from environment variables. - Dynamic Reloading: The
ChannelRunnertracks the modification time (mtime) ofmcp.json. If changes are detected between runs, the session is reloaded and extensions are re-bound automatically.
Sources: entrypoint.sh:11-18, src/agent/setup.ts:171-172, src/agent/setup.ts:241-255
Persistence Layout
In the AWS ECS environment, MCP-related data is stored on EFS to survive task rotations.
The diagram shows how the configuration file is symlinked from the persistent EFS storage into the application's runtime directory.
Sources: entrypoint.sh:5-9, CLAUDE.md:9-11
Tool Execution and UI Feedback
When the agent invokes an MCP tool, the system provides feedback through the Slack interface to inform the user of the ongoing operation.
Tool Labeling
Because the pi-mcp-adapter often proxies multiple MCP calls through a single gateway tool named "mcp", the system includes logic to unwrap these calls into human-readable labels. This ensures the Slack UI shows specific actions (e.g., → mcp search "query") rather than a generic "mcp" label.
Sources: src/agent/events.ts:85-103
Execution Sequence
The interaction between the agent, the MCP adapter, and the Slack surface is handled via an event-driven architecture.
The sequence diagram details how internal session events are translated into user-facing progress updates in Slack.
Sources: src/agent/events.ts:110-120, src/agent/events.ts:125-135
Security and Credentials
MCP servers often require API keys which are managed through the project's security infrastructure:
- AWS Secrets Manager: Keys like
EXA_API_KEYare stored in AWS Secrets Manager. - Task Definition: These secrets are injected as environment variables into the ECS container.
- Adapter Access: The adapter uses these variables to authenticate requests to external MCP servers.
Sources: deploy/cloudformation.yml:615-620, CLAUDE.md:46-49
Conclusion
The Model Context Protocol implementation in pi-digby provides a flexible and extensible way to enhance the agent's capabilities. By using a dynamic adapter and persistent configuration, the system allows for the seamless addition of new tools while maintaining security and providing clear visibility of tool usage to the user.
Sources: src/agent/setup.ts:145-160, src/agent/events.ts:85-103