Host-Mediated Stdio Bridge

Relevant source files

The following files were used as context for generating this wiki page:

• mcp_server_code_execution_mode.py
• ARCHITECTURE.md
• README.md
• HISTORY.md
• GUIDE.md
• STATUS.md
• tests/test_integration.py

The Host-Mediated Stdio Bridge is a core architectural component of the MCP Server Code Execution Mode, designed to provide secure, isolated Python code execution with mediated access to external Model Context Protocol (MCP) servers. The bridge facilitates communication between a rootless container sandbox and the host system using JSON-framed messages over standard input and output (stdio).

This bridge replaces earlier insecure prototypes that utilized in-process sandboxing or raw process spawning. By employing a container-based architecture, the bridge ensures that all cross-boundary operations are explicit, monitored, and subject to host-side mediation. This approach maintains a clear security boundary while allowing the sandboxed environment to discover and invoke tools from host-managed MCP servers.

Sources: HISTORY.md:24-38, ARCHITECTURE.md:5-25, README.md:129-148

Architectural Overview

The architecture consists of three primary layers: the MCP Client (e.g., Claude Desktop), the Host Bridge, and the Container Sandbox. The bridge acts as the central coordinator, exposing a single run_python tool to the client while managing the lifecycle of isolated execution environments.

System Hierarchy and Communication Flow

The following diagram illustrates the relationship between the host system, the container runtime, and the MCP servers.

The bridge mediates all traffic, ensuring the sandbox remains isolated from the network while still being able to interact with tools through the bridge's RPC handlers.

Sources: ARCHITECTURE.md:27-52, README.md:377-386

Core Components

The implementation relies on several key classes and modules within mcp_server_code_execution_mode.py to handle the complexity of IPC and session management.

MCPBridge

The central manager responsible for discovering host-side MCP server definitions, maintaining a pool of client sessions, and initiating execution requests. It scans multiple configuration paths (e.g., ~/MCPs, ~/.config/mcp/servers) to identify available tools.
Sources: mcp_server_code_execution_mode.py:906-930, GUIDE.md:95-125

PersistentMCPClient

Maintains long-running stdio sessions with external MCP servers. By keeping these sessions warm across multiple tool calls, it avoids the latency of repeated "cold starts" during initialization.
Sources: mcp_server_code_execution_mode.py:355-385, ARCHITECTURE.md:65-70

SandboxInvocation

A temporary context manager that prepares the execution environment. It generates a specialized entrypoint.py script, sets up shared IPC volumes, and handles the incoming JSON-RPC requests from the sandbox.
Sources: mcp_server_code_execution_mode.py:821-860, ARCHITECTURE.md:72-76

Component Relationship

Communication Protocol (JSON Stdio Bridge)

The bridge utilizes a custom JSON-framed protocol over stdio to bypass the isolation barriers of the container. The generated entrypoint.py inside the container rewires standard Python sys.stdout and sys.stderr into JSON messages.

Message Types

Message Type	Direction	Description
execute	Host -> Sandbox	Sends the Python source code to be executed.
stdout	Sandbox -> Host	Forwards standard output captured within the sandbox.
stderr	Sandbox -> Host	Forwards standard error captured within the sandbox.
rpc_request	Sandbox -> Host	Requests an MCP tool call or documentation query.
rpc_response	Host -> Sandbox	Returns the result of an MCP tool call.
execution_done	Sandbox -> Host	Signals the completion of the current code block.

Sources: mcp_server_code_execution_mode.py:465-515, ARCHITECTURE.md:88-100

RPC Sequence Diagram

The following sequence shows how the sandbox requests a tool call from a host-managed MCP server via the bridge.

Security Mediation

Security is enforced through "Host Mediation," where the host system controls all interactions between the untrusted sandbox and external services.

1. Capability Dropping: The container is launched with --cap-drop ALL and no-new-privileges to prevent escalation.
2. Resource Limits: The bridge enforces limits on Memory (default 512m), PIDs (default 128), and CPU usage.
3. Namespace Isolation: Containers are launched with --network none and a read-only root filesystem.
4. Implicit Allowlisting: Sandboxed code can only access MCP servers that were explicitly passed in the servers parameter of the run_python call.

Sources: mcp_server_code_execution_mode.py:417-440, README.md:389-405, ARCHITECTURE.md:126-140

Configuration and Runtime

The bridge supports both podman and docker (rootless). It dynamically detects the available runtime and manages lifecycle events, such as starting and stopping the Podman machine.

Key Environment Variables

Variable	Default	Purpose
MCP_BRIDGE_RUNTIME	auto	Force specific runtime (podman/docker).
MCP_BRIDGE_IMAGE	python:3.14-slim	The base image for the sandbox.
MCP_BRIDGE_STATE_DIR	~/MCPs	Base directory for IPC and user tools.
MCP_BRIDGE_TIMEOUT	30	Default execution timeout in seconds.

Sources: mcp_server_code_execution_mode.py:85-105, GUIDE.md:65-90, ARCHITECTURE.md:112-124

Summary

The Host-Mediated Stdio Bridge provides a robust mechanism for executing arbitrary Python code without compromising host security. By centralizing communication through a JSON-framed stdio protocol, the project enables complex MCP tool orchestration within a hardened container environment. This architecture effectively handles tool discovery, persistent state, and resource isolation while maintaining high performance through warm client sessions.