Configuration Reference

Relevant source files

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

• mcp_server_code_execution_mode.py
• GUIDE.md
• README.md
• ARCHITECTURE.md
• STATUS.md
• HISTORY.md

This reference provides a comprehensive overview of the configuration options, environment variables, and discovery mechanisms used by the MCP Server Code Execution Mode bridge. The system is designed to provide a secure, rootless containerized environment for executing Python code while proxying external Model Context Protocol (MCP) servers.

Effective configuration ensures the bridge correctly identifies available runtimes (Podman or Docker), locates external MCP server definitions, and enforces security constraints such as resource limits and network isolation. For a deeper understanding of the system design, see the Architecture Overview.

Environment Variables

The bridge behavior is primarily controlled through environment variables. These settings define the container runtime, resource constraints, and output formatting.

Runtime and Security Configuration

Variable	Default	Description
MCP_BRIDGE_RUNTIME	auto	Specifies the container runtime (podman or docker). If unset, the bridge auto-detects based on available binaries.
MCP_BRIDGE_IMAGE	python:3.14-slim	The container image used for the sandbox.
MCP_BRIDGE_CONTAINER_USER	65534:65534	The UID:GID under which the sandbox process runs inside the container.
MCP_BRIDGE_STATE_DIR	~/MCPs	Host directory used for IPC sockets, generated entrypoints, and temporary state.
MCP_BRIDGE_ALLOW_SELF_SERVER	0 (False)	If set to 1, allows the bridge to recursively launch itself as a nested MCP server.

Sources: mcp_server_code_execution_mode.py:115-132, README.md:468-479, ARCHITECTURE.md:88-97

Resource and Timeout Limits

Variable	Default	Description
MCP_BRIDGE_TIMEOUT	30	Default execution timeout in seconds.
MCP_BRIDGE_MAX_TIMEOUT	120	Maximum allowable timeout in seconds.
MCP_BRIDGE_MEMORY	512m	Memory limit for the container (e.g., 512m, 1g).
MCP_BRIDGE_PIDS	128	Maximum number of processes allowed inside the container.
MCP_BRIDGE_CPUS	host default	CPU quota for the container (e.g., 2.0).
MCP_BRIDGE_RUNTIME_IDLE_TIMEOUT	300	Delay in seconds before the Podman machine auto-shuts down after inactivity.

Sources: mcp_server_code_execution_mode.py:117-123, GUIDE.md:129-158, README.md:468-479

Logging and Output Modes

Variable	Default	Description
MCP_BRIDGE_OUTPUT_MODE	compact	Controls the format of response text. Options: compact (plain text) or toon (Token-Oriented Object Notation).
MCP_BRIDGE_LOG_LEVEL	INFO	Adjusts the verbosity of bridge logs (e.g., DEBUG, INFO, WARNING, ERROR).

Sources: mcp_server_code_execution_mode.py:246-267, README.md:480-481, GUIDE.md:164-169

Server Discovery Mechanism

The bridge automatically aggregates MCP server definitions from multiple configuration files and directories. This allows the bridge to proxy tools from various environments (Claude, VS Code, local projects) into the secure sandbox.

Discovery Flow Diagram

The following diagram illustrates how the bridge scans and prioritizes configuration sources to build the internal server registry.

The bridge scans sources sequentially; if a server name is duplicated across sources, the first one found takes precedence.
Sources: mcp_server_code_execution_mode.py:186-236, README.md:485-502, GUIDE.md:183-207

Supported Configuration Locations

Location	Purpose	Priority
~/MCPs/	Recommended directory for user-defined MCPs.	Highest
~/.config/mcp/servers/	Standard MCP configuration directory.	High
./mcp-servers/	Local project-specific MCP servers.	Medium
~/.claude.json	Claude CLI configuration.	Medium
IDE Settings	Settings from Cursor, Windsurf, or VS Code Global.	Low
Claude Desktop	Legacy Claude Desktop configuration paths.	Lowest

Sources: mcp_server_code_execution_mode.py:186-236, README.md:485-502

Server Configuration Schema

Individual server definitions within a configuration file must follow a specific JSON structure to be recognized by the bridge.

Example Server Definition

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {
        "DEBUG": "true"
      },
      "cwd": "/home/user/workspace"
    }
  }
}

Sources: README.md:507-514, GUIDE.md:218-228

Schema Fields

Field	Type	Required	Description
command	String	Yes	The executable binary to launch the MCP server.
args	List[String]	No	Command-line arguments passed to the server.
env	Object	No	Environment variables provided to the server process.
cwd	String	No	Working directory for the host process. The bridge starts the server here.
description	String	No	Optional summary shown to the LLM during discovery.

Sources: mcp_server_code_execution_mode.py:1123-1135, GUIDE.md:246-270

Execution Environment Configuration

When a code execution request is made, the bridge prepares a specific environment inside the container. This setup is managed by the SandboxInvocation class.

Sandbox Resource Mapping

Path in Host	Path in Sandbox	Purpose
host_dir (tmp)	/ipc	Shared volume for entrypoint.py and RPC handshakes.
~/MCPs/user_tools	/projects	Persistent storage for user_tools.py and memory/ directory.
N/A (tmpfs)	/tmp	Writable, no-execution temporary storage (64MB).
N/A (tmpfs)	/workspace	Writable, primary working directory (128MB).

Sources: mcp_server_code_execution_mode.py:488-498, mcp_server_code_execution_mode.py:910-930, ARCHITECTURE.md:90-97

RPC Transport Logic

The bridge uses a JSON-over-stdio transport to communicate with the sandbox. The entrypoint rewires standard input and output to facilitate this.

Persistent Memory System

The memory system allows data to survive container restarts by mapping to the host filesystem. It is configured to store JSON data in the /projects/memory/ path within the container.

Memory Configuration Parameters

• Host Path: ~/MCPs/user_tools/memory/ (default, varies based on MCP_BRIDGE_STATE_DIR).
• Storage Format: Individual .json files per key.
• Metadata: Supported as an optional dictionary during save_memory calls.

Sources: mcp_server_code_execution_mode.py:613-755, GUIDE.md:387-434, README.md:237-269

Conclusion

Configuration of the MCP Server Code Execution Mode bridge revolves around balancing security isolation with tool accessibility. By utilizing environment variables for resource capping and standard JSON definitions for server discovery, the bridge provides a flexible yet rigid environment suitable for LLM-driven orchestration. The discovery-first architecture ensures that even with hundreds of configured tools, the bridge maintains a constant and efficient token overhead.

Sources: README.md:89-105, ARCHITECTURE.md:120-135, STATUS.md:110-120