System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Server Code Execution Mode bridge is a production-capable, security-first system designed to execute Python code within isolated rootless containers. Its primary purpose is to implement the "Code Execution with MCP" pattern, which allows Large Language Models (LLMs) to discover and interact with multiple MCP servers through a single run_python tool, significantly reducing context window bloat by using a discovery-first architecture.
The system facilitates stateful execution where variables and imports are preserved across calls within a persistent session. It acts as a mediator between an MCP client (such as Claude Desktop or Claude Code) and various host-managed MCP servers, providing a secure sandbox that drops Linux capabilities, disables network access, and enforces strict resource limits.
Sources: ARCHITECTURE.md:3-12, README.md:16-36, STATUS.md:6-15
Core Component Interaction
The architecture is divided into three primary layers: the MCP Client, the Bridge Server, and the Container Sandbox.
The diagram above illustrates the multi-layered communication flow from the LLM agent to the isolated execution environment.
Sources: ARCHITECTURE.md:14-36, README.md:468-479
Bridge Server Components
The Bridge Server is the central orchestrator, handling discovery, lifecycle management, and RPC mediation.
1. MCPBridge and Persistence
The MCPBridge class manages the discovery of MCP server definitions from multiple configuration sources (e.g., ~/MCPs, ~/.config/mcp/servers). It maintains a pool of PersistentMCPClient instances, which keep stdio sessions to host MCP servers warm across multiple tool calls to avoid cold-start latency.
Sources: mcp_server_code_execution_mode.py:1145-1159, ARCHITECTURE.md:42-45
2. Sandbox Invocation and Entrypoint Generation
The SandboxInvocation context manager prepares the execution environment by creating temporary IPC mounts and generating a specialized entrypoint.py. This entrypoint rewires the container's stdio into JSON-framed messages, allowing the bridge to intercept and proxy MCP tool calls from within the sandbox.
Sources: mcp_server_code_execution_mode.py:1072-1100, ARCHITECTURE.md:46-50
3. Discovery Helpers
A significant architectural feature is the "Zero-Context Discovery." Instead of preloading all tool schemas, the bridge exposes discovery helpers within the sandbox via the mcp.runtime module.
Sources: README.md:129-150, ARCHITECTURE.md:51-58
| Helper Function | Description |
|---|---|
discovered_servers() | Lists all configured servers available for loading. |
query_tool_docs(server) | Hydrates schemas for a specific server on-demand. |
search_tool_docs(query) | Performs fuzzy search across loaded tools. |
capability_summary() | Returns a manual of sandbox capabilities. |
Sources: mcp_server_code_execution_mode.py:686-778, README.md:209-222
Security and Isolation Model
The system utilizes rootless containers (Podman or Docker) to ensure the sandbox operates entirely within the user namespace without privileged helpers.
Container Constraints
The execution environment is heavily restricted to prevent sandbox escapes and resource abuse:
- Networking: Disabled via
--network none. - Filesystem: The root filesystem is read-only (
--read-only), with only specifictmpfsmounts for/tmpand/workspacebeing writable. - Privileges: Enforces
no-new-privilegesand drops all Linux capabilities (--cap-drop ALL). - Identity: Runs as an unprivileged user (UID/GID
65534:65534).
Sources: mcp_server_code_execution_mode.py:440-464, README.md:594-610, ARCHITECTURE.md:89-105
Resource Limits Configuration
Resource limits are configurable via environment variables, as shown in the table below:
| Environment Variable | Default Value | Description |
|---|---|---|
MCP_BRIDGE_MEMORY | 512m | Maximum RAM allocated to the container. |
MCP_BRIDGE_PIDS | 128 | Maximum number of concurrent processes. |
MCP_BRIDGE_TIMEOUT | 30s | Default execution time limit. |
MCP_BRIDGE_MAX_TIMEOUT | 120s | Maximum allowable timeout override. |
Sources: mcp_server_code_execution_mode.py:126-135, GUIDE.md:104-123
Execution Lifecycle
The following sequence diagram represents a typical code execution request involving an external MCP tool call.
The lifecycle ensures that external tool calls are mediated by the host bridge, maintaining security boundaries.
Sources: mcp_server_code_execution_mode.py:1330-1375, ARCHITECTURE.md:73-86
Persistent Memory and State
The bridge implements a specialized memory system that allows agents to persist data and logic across different container sessions.
Storage Architecture
- User Tools: Persistent functions saved via
save_tool(func)are stored in/projects/user_tools.py. - Memory Store: Structured JSON data saved via
save_memory(key, value)is stored in/projects/memory/. - Host Mapping: The
/projectsdirectory in the container maps to~/MCPs/user_tools/on the host, ensuring data survives container restarts.
Sources: mcp_server_code_execution_mode.py:596-665, README.md:386-425, GUIDE.md:428-440
Conclusion
The MCP Server Code Execution Mode architecture provides a robust bridge between AI agents and local tools. By combining a persistent rootless container sandbox with a mediated RPC proxy system, it achieves a balance between high-performance, stateful execution and stringent security requirements. The discovery-first approach effectively solves the context window limitations of traditional MCP implementations, making it suitable for scaling to hundreds of available tools.
Sources: STATUS.md:129-132, README.md:653-659, HISTORY.md:112-117