Prerequisites & Installation

Relevant source files

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

• README.md
• GUIDE.md
• pyproject.toml
• mcp_server_code_execution_mode.py
• ARCHITECTURE.md
• requirements.txt

The MCP Server Code Execution Mode bridge provides a secure, containerized environment for executing Python code through the Model Context Protocol (MCP). The primary purpose of the installation process is to establish a bridge between an LLM agent and a rootless container runtime (Podman or Docker), enabling the agent to discover, call, and compose multiple MCP tools within a secure sandbox.

The installation and setup ensure that the system adheres to a "Discovery-First" architecture. This reduces context overhead significantly (from ~30k tokens to ~200 tokens) by allowing the agent to write Python code to hydrate tool schemas on demand. The high-level flow involves setting up the host environment, configuring the container runtime, and registering the bridge with an MCP client like Claude.

Sources: README.md:21-40, ARCHITECTURE.md:3-30

System Prerequisites

Before installing the bridge, the host system must meet specific software requirements to support the containerized sandbox and Python execution.

Python Environment

• Version: Python 3.11 or higher is required.
• Dependency Management: uv is the recommended tool for managing the project environment and dependencies.
• Pydantic Compatibility: For Python 3.14+, pydantic >= 2.12.0 is required to avoid runtime failures related to typing module shadowing.

Sources: README.md:280-285, GUIDE.md:65-75, mcp_server_code_execution_mode.py:65-120

Container Runtimes

The bridge requires a rootless container runtime to maintain security isolation.

Runtime	Recommendation	Installation Command (Examples)
Podman	Recommended	brew install podman (macOS) or apt-get install podman (Linux)
Docker	Supported	brew install --cask docker (macOS) or get.docker.com script (Linux)

Sources: README.md:286-292, GUIDE.md:20-45

Required Container Image

The bridge defaults to using a slim Python image for the sandbox.

• Default Image: python:3.14-slim (configurable via MCP_BRIDGE_IMAGE).
• Manual Pull: podman pull python:3.13-slim (or current version) to ensure availability.

Sources: README.md:294-297, mcp_server_code_execution_mode.py:127

Installation Steps

The installation process involves syncing dependencies and configuring the bridge to run as an MCP server.

1. Dependency Synchronization

Use uv to install the core SDK and other required libraries defined in pyproject.toml and requirements.txt.

uv sync

Sources: README.md:310-313, requirements.txt:1-8

2. Bridge Registration

The bridge must be registered with an MCP client (e.g., Claude Desktop, Claude Code, or OpenCode). This is typically done by editing a JSON configuration file.

Example Registration (Claude Desktop):

{
  "mcpServers": {
    "mcp-server-code-execution-mode": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/elusznik/mcp-server-code-execution-mode%22%2C
        "mcp-server-code-execution-mode",
        "run"
      ],
      "env": {
        "MCP_BRIDGE_RUNTIME": "podman"
      }
    }
  }
}

Sources: README.md:323-343, GUIDE.md:100-115

Installation Data Flow

The following diagram illustrates the relationship between the host, the dependencies, and the container runtime during setup.

The diagram shows the sequential dependencies required to move from a bare host to a functional MCP agent connection.
Sources: ARCHITECTURE.md:5-25, GUIDE.md:15-120

Configuration & Environment Variables

Post-installation, the bridge behavior is controlled primarily through environment variables.

Core Configuration

Variable	Default	Description
MCP_BRIDGE_RUNTIME	auto-detect	Explicitly set to podman or docker.
MCP_BRIDGE_STATE_DIR	~/MCPs	Host directory for IPC sockets and temp state.
MCP_BRIDGE_LOG_LEVEL	INFO	Logging verbosity (DEBUG, INFO, WARNING, etc.).
MCP_BRIDGE_OUTPUT_MODE	compact	Response format: compact text or toon blocks.

Sources: README.md:465-475, GUIDE.md:148-180

Sandbox Resource Limits

Variable	Default	Description
MCP_BRIDGE_MEMORY	512m	Memory limit for the container.
MCP_BRIDGE_PIDS	128	Max number of processes inside the sandbox.
MCP_BRIDGE_TIMEOUT	30s	Default execution timeout.
MCP_BRIDGE_RUNTIME_IDLE_TIMEOUT	300s	Delay before shutting down Podman machine.

Sources: README.md:465-475, mcp_server_code_execution_mode.py:127-140

Verifying the Installation

To verify the installation, the bridge can be run directly from the command line to check for discovery logs.

uv run python mcp_server_code_execution_mode.py

Upon startup, the bridge scans multiple locations for existing MCP server configurations to proxy.

• Discovery Check: The logs should indicate loaded servers (e.g., INFO - Loaded MCP servers: filesystem).
• Runtime Check: The bridge will lazily detect the container runtime only when a code execution is requested.

Sources: README.md:500-530, GUIDE.md:200-210, mcp_server_code_execution_mode.py:1120-1140

Logic Flow of Discovery

The bridge searches for existing tool configurations across several paths on the host.

This diagram outlines the automatic discovery logic that occurs during initialization to populate the mcp.runtime search index.
Sources: mcp_server_code_execution_mode.py:165-210, GUIDE.md:190-215

Conclusion

A successful installation requires a properly configured Python environment and a functioning rootless container runtime. By registering the bridge as an MCP server, users enable their LLM agents to perform high-performance, cost-effective tool orchestration within a hardened security boundary.

Sources: README.md:100-110, ARCHITECTURE.md:95-110