The run_python Tool
Relevant source files
The following files were used as context for generating this wiki page:
The run_python tool is the core interface of the MCP Server Code Execution Mode bridge. It provides a secure, stateful, and persistent Python execution environment (sandbox) where Large Language Models (LLMs) can execute code, perform data analysis, and orchestrate calls to other Model Context Protocol (MCP) servers. By consolidating multiple tool definitions into a single execution entry point, it significantly reduces context window overhead from tens of thousands of tokens to approximately 200 tokens.
Sources: mcp_server_code_execution_mode.py:1296-1303, README.md:104-125, ARCHITECTURE.md:4-10
Architecture and Execution Model
The tool operates by launching a rootless container (Podman or Docker) that serves as a locked-down sandbox. This sandbox is stateful, meaning variables, functions, and imports are preserved across subsequent calls within the same session. The bridge manages a persistent pool of MCP clients on the host and proxies them into the container using a JSON-framed stdio transport.
High-Level Component Flow
The following diagram illustrates the lifecycle of a single run_python invocation:
Tool Specification and Input Schema
The run_python tool is registered with the following parameters to control execution behavior and resource availability.
| Parameter | Type | Default | Description |
|---|---|---|---|
code | string | (Required) | Python source code to execute in the sandbox. |
servers | array | [] | Optional list of MCP servers to mount as mcp_<alias> proxies. |
timeout | integer | 30 | Execution timeout in seconds (Max: 120s). |
Sources: mcp_server_code_execution_mode.py:1305-1329
The Sandbox Environment
The sandbox is designed for high security and isolation while maintaining functional parity with a standard Python environment.
Security Constraints
Execution is restricted by multiple layers of isolation enforced by the container runtime:
- Network: Completely disabled (
--network none). - Filesystem: Read-only root filesystem with
tmpfsmounts for/tmpand/workspace. - Privileges: Dropped Linux capabilities and enforced
no-new-privileges. - User: Runs as an unprivileged user (UID:GID 65534:65534).
- Resource Limits: Configurable memory, PID, and CPU caps.
Sources: mcp_server_code_execution_mode.py:363-388, README.md:373-388, ARCHITECTURE.md:113-124
Proxying and Discovery
Inside the sandbox, requested MCP servers are made available through auto-generated proxy modules. The LLM can use the mcp.runtime module for discovery:
runtime.discovered_servers(): Lists all servers known to the bridge.runtime.query_tool_docs(server): Fetches specific tool schemas on demand.runtime.search_tool_docs(query): Fuzzy searches across available tools.
Persistent Memory and State
A key feature of the tool is its persistence across sessions. Data and logic can be saved to the host and re-imported in later runs.
Persistence Mechanisms
- User Tools: LLMs can save functions using
save_tool(func), which appends the source code to/projects/user_tools.pyon the host. - Memory System: A JSON-based key-value store available via
save_memory(key, value)andload_memory(key).
| Function | Purpose | Storage Location |
|---|---|---|
save_tool(func) | Persists Python functions across restarts | /projects/user_tools.py |
save_memory(k, v) | Saves structured JSON data | /projects/memory/*.json |
update_memory(k, f) | Atomic read-modify-write for state | /projects/memory/*.json |
Sources: mcp_server_code_execution_mode.py:518-620, STATUS.md:27-34, GUIDE.md:433-470
Output and Error Handling
The tool returns a CallToolResult with dual representation:
- Compact Text: A human-readable summary of
stdout,stderr, and exit codes. - Structured Content: A JSON object containing the trimmed payload of the execution results.
Execution Lifecycle within the Bridge
The bridge manages the transition from a raw code string to a structured response:
Summary
The run_python tool transforms an LLM into an active programmer by providing a secure, persistent, and tool-aware execution environment. By leveraging rootless containers and a discovery-first architecture, it ensures that even environments with hundreds of MCP tools remain efficient and secure, allowing for complex multi-step workflows that simple tool calling cannot achieve.
Sources: README.md:12-25, STATUS.md:5-10