Welcome to MCP Code Execution Server
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Code Execution Server is a secure bridge implementation of the "Code Execution with MCP" pattern. It enables LLMs to interact with Model Context Protocol (MCP) tools through a sandboxed Python environment rather than direct tool calling. By exposing a single run_python tool, the server allows agents to write Python code to discover, orchestrate, and compose multiple MCP servers while significantly reducing context token overhead.
The system utilizes rootless container technology (Podman or Docker) to provide a hardened, network-isolated, and resource-limited execution environment. This architecture ensures that untrusted, LLM-generated code runs in a zero-trust sandbox while maintaining persistent sessions and memory across multiple calls.
Sources: README.md:16-43, ARCHITECTURE.md:3-10, STATUS.md:5-10
System Architecture
The server acts as a mediator between an MCP Client (such as Claude Desktop) and a containerized sandbox. It manages a pool of persistent MCP clients on the host, which are proxied into the container via a JSON-framed stdio bridge.
High-Level Component Flow
The following diagram illustrates the request flow from the initial LLM query to code execution within the isolated sandbox.
The bridge prepares a fresh container for execution, mounting a temporary IPC volume that contains the generated entrypoint script.
Sources: ARCHITECTURE.md:12-35, mcp_server_code_execution_mode.py:910-945
Core Features and Capabilities
Discovery-First Pattern
Instead of preloading hundreds of tool schemas into the LLM context, the bridge utilizes a discovery-first approach. The initial overhead is constant at approximately 200 tokens, regardless of the number of tools available. The LLM uses specialized runtime helpers to hydrate only the schemas it needs on demand.
| Feature | Description |
|---|---|
| Zero-Context Discovery | Enumerate servers and tools only when needed via runtime helpers. |
| Persistent Sessions | Variables, imports, and state are retained across multiple code executions. |
| Multi-Server Proxying | Access any host-configured MCP server as a Python module (e.g., mcp_github). |
| Hardened Isolation | Rootless containers with no network, read-only rootfs, and dropped capabilities. |
| Memory System | JSON-based storage for cross-session data persistence. |
Sources: README.md:69-95, STATUS.md:15-30, GUIDE.md:280-320
Security Model
The sandbox is built on a "Security First" philosophy, enforcing strict constraints at the container runtime level to prevent escapes and resource abuse.
- Network Isolation: Containers are launched with
--network none. - Filesystem Security: Root filesystem is read-only;
/workspaceand/tmpusetmpfs. - Privilege Control: Enforces
no-new-privilegesand drops all Linux capabilities (--cap-drop ALL). - Resource Limits: Configurable caps on Memory (default 512m), PIDs (default 128), and CPU.
- User Identity: Runs as an unprivileged user (UID 65534:65534).
Sources: mcp_server_code_execution_mode.py:460-490, ARCHITECTURE.md:95-108, README.md:347-360
Persistent Memory and User Tools
The system provides two mechanisms for state persistence that survive container restarts. Both are stored in the host directory ~/MCPs/user_tools/.
Memory System
The memory system allows the storage of JSON-serializable data.
save_memory(key, value): Stores data with optional metadata.load_memory(key): Retrieves stored JSON values.update_memory(key, fn): Performs atomic read-modify-write operations.list_memories(): Discovers all saved keys and their metadata.
User Tool Persistence
The save_tool(func) helper allows agents to save custom Python functions. These functions are appended to /projects/user_tools.py and are automatically imported into the global namespace in future sessions.
Sources: mcp_server_code_execution_mode.py:615-780, GUIDE.md:392-440
Configuration and Discovery
The bridge automatically discovers MCP server configurations from various standard locations, including Claude Code, Windsurf, Cursor, and standard MCP config paths.
Configuration Environment Variables
| Variable | Default | Description |
|---|---|---|
MCP_BRIDGE_RUNTIME | auto | Force podman or docker. |
MCP_BRIDGE_IMAGE | python:3.14-slim | The base container image. |
MCP_BRIDGE_TIMEOUT | 30 | Default execution timeout in seconds. |
MCP_BRIDGE_STATE_DIR | ~/MCPs | Host directory for IPC and persistence. |
MCP_BRIDGE_OUTPUT_MODE | compact | Response format (compact or toon). |
Sources: mcp_server_code_execution_mode.py:126-145, GUIDE.md:120-155
Discovery Sequence
When the run_python tool is invoked, the bridge follows this logic to prepare the environment:
Implementation Details
Response Rendering
The bridge supports two primary output modes controlled by MCP_BRIDGE_OUTPUT_MODE:
- Compact (Default): Returns plain text stdout/stderr with a trimmed
structuredContentpayload. It automatically filters noise lines and empty fields to minimize token usage. - TOON Mode: Uses Token-Oriented Object Notation blocks to provide deterministic tokenization for downstream agents.
Sources: mcp_server_code_execution_mode.py:255-330, README.md:270-285
Sandbox Helpers
Inside the sandbox, the mcp.runtime module provides the following key functions:
discovered_servers(): Lists all known servers on the host.query_tool_docs(server, detail="summary"): Hydrates tool schemas.search_tool_docs(query): Performs fuzzy keyword search across all loaded servers.capability_summary(): Returns a textual manual of sandbox features.
Sources: mcp_server_code_execution_mode.py:790-830, GUIDE.md:325-370
Summary
The MCP Code Execution Server transforms the LLM from a simple tool caller into a programmer capable of orchestrating complex workflows. By providing a secure, persistent, and discovery-oriented Python environment, it solves the problem of "context bankruptcy" while maintaining high levels of security and extensibility for data science and AI applications.