MCP Runtime Engine
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Runtime Engine is the core execution framework of the Continuous Claude system, responsible for orchestrating interactions between AI agents and external tools via the Model Context Protocol (MCP). It provides a high-performance, typed environment that manages tool discovery, connection lifecycle, and execution through a "progressive disclosure" pattern that significantly reduces token overhead.
The engine supports multiple transport layers, including stdio, SSE, and HTTP, and implements lazy-loading via the McpClientManager to ensure connections are only established when a specific tool is invoked. This architecture allows the system to scale to numerous MCP servers without bloating the initial context or memory footprint.
Sources: CLAUDE.md:124-129, src/runtime/mcp_client.py
Architecture and Components
The MCP Runtime Engine is built around four primary functional areas: Configuration Management, Client Orchestration, Wrapper Generation, and Schema Discovery.
McpClientManager
The McpClientManager serves as a singleton coordinator that handles the lifecycle of connections to various MCP servers. It uses lazy initialization, meaning it loads configurations first and only establishes a physical connection (stdio subprocess or network socket) when call_tool() is executed for a specific server.
The diagram above shows the lazy-loading logic used by the manager to minimize resource consumption until a tool is actually needed.
Sources: CLAUDE.md:130-132, src/runtime/mcp_client.py
Execution Harness
src/runtime/harness.py provides the entry point for executing scripts within the MCP context. It handles asynchronous initialization, signal management (for clean shutdowns), and ensures the McpClientManager is correctly cleaned up after script execution.
Sources: src/runtime/harness.py, CLAUDE.md:133
Tool Execution Flow
The engine implements a standard naming convention where tools are addressed as serverName__toolName. This double-underscore separator allows the manager to route requests to the correct server instance.
This sequence illustrates the interaction between the runtime components and external MCP server processes.
Sources: CLAUDE.md:131, src/runtime/generate_wrappers.py:38-42
Typed Wrapper Generation
To enable type safety and autocompletion for developers, the engine includes a generate_wrappers.py module. This module introspects configured MCP servers and generates Pydantic models and asynchronous Python wrappers in the servers/ directory.
Features of Generated Wrappers
- Progressive Disclosure: Only the necessary schemas are imported, reducing token counts by up to 99.6% compared to raw schema loading.
- Field Normalization: Automatically converts inconsistent casing (e.g., PascalCase to camelCase) to ensure a consistent developer experience across different servers.
- Defensive Unwrapping: Handles diverse response formats, ensuring the
valuefield is extracted correctly.
| Component | Description | File Path |
|---|---|---|
params_model | Pydantic model for tool input validation | servers/<server>/<tool>.py |
wrapper_func | Async function to invoke the tool via call_mcp_tool | servers/<server>/<tool>.py |
barrel_export | Exports all tools for easy importing | servers/<server>/__init__.py |
Sources: src/runtime/generate_wrappers.py:15-85, CLAUDE.md:134-136
Configuration and Transport Support
The engine supports three primary transport types, allowing it to communicate with local CLI tools and remote web services.
Configuration Format
Configurations are typically stored in mcp_config.json or .mcp.json. The environment variables are managed via ${VAR} placeholders, which are resolved at runtime.
{
"mcpServers": {
"git": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-git", "--repository", "."]
},
"github": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
}
}
}
Sources: mcp_config.json:1-30, CLAUDE.md:151-177
Supported Transports
| Transport | Description | Implementation Detail |
|---|---|---|
| stdio | Local subprocess communication | Uses StdioServerParameters |
| SSE | Server-Sent Events for remote tools | Uses sse_client with URL/Headers |
| HTTP | Streamable HTTP for web-based MCP | Uses streamablehttp_client |
Sources: src/runtime/generate_wrappers.py:270-285, CLAUDE.md:144-146
Safety and Discovery
The src/runtime/generate_test_params.py module classifies tools to prevent accidental data loss or destructive actions during automated discovery.
Safety Classification Logic
The engine uses regex patterns and keyword analysis to categorize tools into three states:
- SAFE: Read-only operations (
get_,list_,search_). - DANGEROUS: Mutating operations (
delete_,update_,drop_). - UNKNOWN: Tools with ambiguous names requiring manual review.
Summary
The MCP Runtime Engine provides a robust, type-safe infrastructure for AI tool orchestration. By combining lazy-loading client management with automated wrapper generation and multi-transport support, it allows the Continuous Claude system to interact with a vast ecosystem of tools while maintaining minimal context overhead and high execution reliability.