Persistent MCP Client Pool
Relevant source files
The following files were used as context for generating this wiki page:
The Persistent MCP Client Pool is a core architectural component of the mcp-server-code-execution-mode bridge. Its primary purpose is to maintain active, warm stdio sessions with discovered MCP servers across multiple code execution requests. This eliminates the latency associated with "cold starts" by keeping the connection to external tools alive even after a specific Python execution block has completed.
Within the project, this system ensures that the LLM agent can interact with various external tools (like filesystems, databases, or APIs) via sandboxed code without the overhead of re-initializing the transport layer for every call. The pool manages the lifecycle of PersistentMCPClient instances, handling their startup, tool discovery, and clean shutdown.
Sources: ARCHITECTURE.md:21-25, STATUS.md:21-25, README.md:255-257
Core Components
The pool relies on several key classes and functions to manage server configurations and active sessions.
PersistentMCPClient Class
This class encapsulates a single persistent stdio session. It manages the underlying stdio_client and ClientSession, and provides a filtered reader to handle common protocol noise such as blank lines.
| Component | Responsibility |
|---|---|
stdio_cm | Manages the asynchronous context for the stdio transport. |
_session | Holds the active ClientSession for protocol interaction. |
_forward_task | An asynchronous task that reads from the server and filters out benign JSON parse errors. |
_captured_stderr | A temporary file used to capture and store server-side errors for diagnostics. |
Sources: mcp_server_code_execution_mode.py:441-456, mcp_server_code_execution_mode.py:476-480, mcp_server_code_execution_mode.py:490-496
MCPBridge Client Management
The MCPBridge class acts as the coordinator for the pool. It tracks active clients in a self.clients dictionary and maintains a set of loaded_servers.
discover_servers(): Scans various system paths (e.g.,~/.config/mcp/servers/,~/.claude.json) to populate the available server definitions.load_server(server_name): Instantiates aPersistentMCPClientif one does not already exist for the requested server, ensuring it is "warm" before execution.
Sources: mcp_server_code_execution_mode.py:1011-1014, mcp_server_code_execution_mode.py:1020-1025, mcp_server_code_execution_mode.py:1145-1155
Data Flow and Session Lifecycle
The lifecycle of a client within the pool begins with discovery and ends with a graceful shutdown when the bridge itself terminates.
The diagram above shows how servers are kept "warm" between execution calls.
Sources: mcp_server_code_execution_mode.py:1145-1165, mcp_server_code_execution_mode.py:1185-1195, ARCHITECTURE.md:54-65
Metadata Caching and Discovery
To keep the LLM's context window small (roughly 200 tokens), the pool does not preload all tool schemas. Instead, it uses a lazy discovery pattern mediated by the bridge.
Lazy Hydration
When a server is first loaded, the bridge calls list_tools() and caches the results in _server_metadata_cache. This metadata includes:
- Server aliases (to prevent name collisions in Python).
- Tool names and descriptions.
- Input schemas (only hydrated on demand).
Sources: mcp_server_code_execution_mode.py:1210-1225, mcp_server_code_execution_mode.py:1260-1265, README.md:231-236
RPC Mediation
Active clients in the pool are exposed to the sandbox through SandboxInvocation.handle_rpc. When sandboxed code calls a tool, the request flows back to the host, which dispatches it to the correct PersistentMCPClient.
Configuration Sources
The pool populates its available servers by searching several high-priority and legacy locations.
| Priority | Location Name | Path Example |
|---|---|---|
| 1 | User MCPs | ~/MCPs/ |
| 2 | Standard MCP | ~/.config/mcp/servers/ |
| 3 | Local Project | ./mcp-servers/ |
| 4 | Claude Code | ~/Library/Application Support/Claude Code/claude_code_config.json |
| 5 | OpenCode | ~/.opencode.json |
Sources: mcp_server_code_execution_mode.py:157-190, GUIDE.md:94-115
Error Handling and Diagnostics
The PersistentMCPClient implements specific logic to handle the "noise" often generated by MCP servers:
- Benign Noise Filtering: It ignores JSON parse errors caused by stray blank lines (
\n) in the stdio stream. - Stderr Capture: It redirects the server's raw stderr to a temporary file (
_captured_stderr) to allow developers to troubleshoot startup failures or protocol violations without polluting the main transport channel. - Timeout Enforcement: The pool respects both global defaults (
MCP_BRIDGE_TIMEOUT) and per-call overrides, ensuring that a hanging external tool does not block the bridge indefinitely.
Sources: mcp_server_code_execution_mode.py:465-475, mcp_server_code_execution_mode.py:530-535, GUIDE.md:386-395
Conclusion
The Persistent MCP Client Pool is essential for the high-performance orchestration of external tools within the isolated Python sandbox. By maintaining long-lived connections and lazy-loading schemas, it minimizes token usage while maximizing execution speed and reliability across multiple agent-driven workflows.
Sources: README.md:255-257, STATUS.md:43-46