Features 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 infrastructure component designed to provide secure, isolated, and stateful Python code execution environments. It implements the "Code Execution with MCP" pattern, allowing Large Language Models (LLMs) to interact with a vast ecosystem of Model Context Protocol (MCP) tools through a single, context-efficient run_python interface.
The system's primary goal is to solve "MCP Token Bankruptcy" by replacing massive tool schema preloading with a discovery-first architecture. Instead of consuming tens of thousands of tokens to describe hundreds of tools, the bridge uses a constant ~200-token overhead. The LLM then writes Python code to dynamically discover, hydrate, and invoke the specific tools it needs within a rootless container sandbox.
Sources: README.md:16-56, STATUS.md:6-12
Core Features and Components
Secure Containerized Sandbox
The execution environment is built on a rootless container architecture (using Podman or Docker) that enforces strict security boundaries. Each execution is isolated from the host and other processes.
| Security Feature | Implementation Details |
|---|---|
| Network Isolation | Completely disabled via --network none |
| Filesystem Access | Read-only root filesystem; temporary tmpfs for /tmp and /workspace |
| Privilege Level | Runs as unprivileged user (UID 65534); drops all Linux capabilities |
| Resource Limits | Configurable caps for Memory, PIDs, CPU, and Timeouts |
| Isolation | Enforced via no-new-privileges and container boundaries |
Sources: mcp_server_code_execution_mode.py:465-492, README.md:464-477, ARCHITECTURE.md:124-138
Discovery-First Tool Management
The bridge provides a zero-context discovery mechanism. The LLM is provided with small "helper" summaries that allow it to explore available MCP servers and tools on demand.
The diagram above illustrates how the LLM interacts with discovery helpers to hydrate schemas only when needed, maintaining a minimal context window.
Sources: README.md:91-118, mcp_server_code_execution_mode.py:902-957
Persistent Memory and State
Unlike standard stateless tool invocations, this bridge maintains state across calls. This is achieved through two mechanisms:
- Stateful Sandbox: Variables, imports, and functions defined in one
run_pythoncall are preserved for subsequent calls within the same session. - Persistent Memory System: A JSON-based storage system that persists data to the host filesystem, allowing information to survive container restarts and session resets.
Key Memory Functions:
save_memory(key, value): Stores JSON-serializable data.load_memory(key): Retrieves stored data.update_memory(key, fn): Performs atomic read-modify-write operations.list_memories(): Lists all stored keys and metadata.
Sources: STATUS.md:25-31, GUIDE.md:389-436, mcp_server_code_execution_mode.py:656-788
System Architecture and Data Flow
The bridge acts as a mediator between the MCP Client (the LLM interface), the container sandbox, and external MCP servers.
This sequence shows the mediation of tool calls through the host to ensure security and persistence.
Sources: mcp_server_code_execution_mode.py:539-586, ARCHITECTURE.md:7-40
Host-Mediated Proxying
The SandboxInvocation class manages the lifecycle of a single code execution request. It prepares IPC resources, mounts necessary volumes (like /ipc and /projects), and services JSON-RPC requests from the sandbox.
Key components in the proxying flow:
PersistentMCPClient: Keeps stdio sessions to external MCP servers warm across multiple invocations to prevent cold-start latency.- JSON-Framed Stdio: The bridge uses line-delimited JSON messages to communicate with the container, avoiding protocol mismatches common in simpler prototypes.
Sources: mcp_server_code_execution_mode.py:284-332, ARCHITECTURE.md:46-62, HISTORY.md:26-31
Configuration and Discovery
The bridge automatically discovers MCP server configurations from various standard locations on the host system.
| Configuration Source | Path/Location |
|---|---|
| User MCPs | ~/MCPs/*.json |
| Standard MCP | ~/.config/mcp/servers/*.json |
| Claude Config | ~/.claude.json, claude_desktop_config.json |
| IDEs | Cursor, Windsurf, VS Code global/workspace settings |
| Environment | MCP_SERVERS_CONFIG |
Sources: mcp_server_code_execution_mode.py:119-158, GUIDE.md:144-167
Environment Variable Tuning
Execution parameters can be tuned via environment variables:
MCP_BRIDGE_RUNTIME: Force use ofpodmanordocker.MCP_BRIDGE_TIMEOUT: Default execution timeout (default 30s).MCP_BRIDGE_MEMORY: Memory limit (default 512m).MCP_BRIDGE_OUTPUT_MODE: Toggle betweencompacttext and structuredtoonformats.
Sources: README.md:414-432, GUIDE.md:104-135
Conclusion
The MCP Server Code Execution Mode bridge provides a highly secure, context-optimized platform for LLM agency. By shifting from static tool definitions to a dynamic, code-first discovery model, it enables complex multi-tool orchestrations while maintaining a lightweight context footprint. Its use of rootless containers and persistent state makes it suitable for data science and enterprise security requirements.
Sources: README.md:144-154, HISTORY.md:126-131