Registering with MCP Clients
Relevant source files
The following files were used as context for generating this wiki page:
Registering with Model Context Protocol (MCP) clients is the process of configuring an AI agent or host application (such as Claude Desktop, Claude Code, or VS Code) to recognize and communicate with the mcp-server-code-execution-mode bridge. This registration enables the client to delegate code execution tasks to a secure, containerized Python environment.
The registration process primarily involves adding a JSON configuration entry to the client's settings. This entry specifies how to launch the bridge—typically using uvx or python—and defines essential environment variables like the container runtime (podman or docker). Once registered, the bridge acts as a primary tool provider, exposing the run_python tool to the LLM.
Sources: README.md:275-298, GUIDE.md:65-90, ARCHITECTURE.md:5-25
Configuration Methods
MCP clients require a standardized JSON structure to initialize the connection over stdio. The bridge can be launched directly from a git repository using uvx or from a local installation.
Automated Registration via UVX
The recommended way to register the bridge is through uvx, which handles environment isolation automatically.
{
"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:280-296, GUIDE.md:71-85
Manual Local Registration
For developers working with a local checkout, the bridge can be registered using the Python interpreter.
{
"mcpServers": {
"mcp-server-code-execution-mode": {
"command": "python3",
"args": ["/path/to/mcp_server_code_execution_mode.py"],
"env": {
"MCP_BRIDGE_RUNTIME": "docker"
}
}
}
}
Sources: GUIDE.md:88-100, README.md:270-273
Client-Specific Configuration Paths
The bridge is designed to be recognized by various MCP-compatible clients. Each client looks for configuration in specific filesystem locations.
| Client | Configuration Path |
|---|---|
| Claude Code | ~/.config/mcp/servers/mcp-server-code-execution-mode.json |
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| OpenCode | ~/.opencode.json |
| VS Code (Global Linux) | ~/.config/Code/User/settings.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
Sources: GUIDE.md:65-80, mcp_server_code_execution_mode.py:165-210
Architecture of Client Interaction
When a client registers and starts the bridge, a multi-layered communication flow is established. The client communicates with the Bridge via stdio using JSON-RPC, while the Bridge manages a rootless container for actual execution.
The diagram shows how the MCP Client acts as the entry point, communicating with the Bridge, which then orchestrates the containerized sandbox and proxies other MCP servers.
Sources: ARCHITECTURE.md:8-35, mcp_server_code_execution_mode.py:530-580
Essential Environment Variables
Registration often requires setting specific environment variables in the env block of the configuration to ensure the bridge functions correctly with the host's container runtime.
| Variable | Description | Recommended Value |
|---|---|---|
MCP_BRIDGE_RUNTIME | Specifies the container engine. | podman or docker |
MCP_BRIDGE_IMAGE | The Python image used for the sandbox. | python:3.14-slim |
MCP_BRIDGE_STATE_DIR | Directory for IPC sockets and state. | ~/MCPs |
MCP_BRIDGE_LOG_LEVEL | Verbosity of the bridge logging. | INFO or WARNING |
Sources: README.md:465-485, GUIDE.md:110-135, mcp_server_code_execution_mode.py:100-115
Server Discovery Logic
Upon registration, the bridge initializes its discovery system. It does not just act as a tool; it acts as a gateway to other MCP servers already configured in the user's environment.
The sequence diagram illustrates the discovery process that occurs immediately after the client starts the bridge, ensuring the bridge knows which other tools it can proxy.
Sources: mcp_server_code_execution_mode.py:1000-1050, GUIDE.md:150-170
Handling Self-Reference
To prevent infinite recursion (the bridge trying to launch another instance of itself as a proxied server), the bridge automatically skips configuration entries matching its own name or launch command. This can be overridden by setting MCP_BRIDGE_ALLOW_SELF_SERVER=1.
Sources: mcp_server_code_execution_mode.py:120-130, README.md:520-525
Verification of Successful Registration
After configuring the client and restarting it, registration can be verified through the following indicators:
- Tool Availability: The LLM should have access to exactly one tool from this server:
run_python. - Resource Access: The resource
resource://mcp-server-code-execution-mode/capabilitiesshould be available, providing a summary of sandbox helpers. - Bridge Logs: If running the client in a terminal (like Claude Code), the bridge will log:
INFO - Discovered X MCP serversandINFO - Loaded MCP server ...when tools are invoked.
Sources: mcp_server_code_execution_mode.py:1055-1065, GUIDE.md:215-225, STATUS.md:25-45