MCP Code Mode
Prototype implementation for the Code Execution MCP Server with DSpy. The "Code Execution with MCP" architecture combines the strengths of Large Language Models at code generation with the Model Context Protocol for tool integration. This system enables an AI agent to write Python code that runs in an isolated sandbox while seamlessly calling external MCP tools.
Quick Start
1. Installation
Requires Python 3.11+ and Node.js 20+.
# Create virtual environment
python3.11 -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -e .[dev]
# Install Node.js dependencies for reference servers
npm install -g npm@latest
2. Configuration
Copy the example environment file and configure secrets:
cp .env.example .env
Configure your MCP servers in mcp_servers.json:
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/your-working-folder"],
"description": "Local file system operations"
}
}
}
3. Running the Server
Launch the Code Execution MCP server:
python -m mcp_code_mode.executor_server
4. Verification
Verify your setup by running the debug executor script. This script simulates an MCP client, connects to the server, and runs a test task to ensure the agent and tools are working correctly.
Before running the script:
- Configure the MCP servers you want to interact with in
mcp_servers.json. - Define the specific task you want the agent to perform by editing the
taskvariable inscripts/debug_executor.py.
python scripts/debug_executor.py
Development Commands
| Command | Description |
|---|---|
pytest |
Run all tests |
ruff check . |
Lint the codebase |
black . |
Format the codebase |
mypy src |
Type check the source |
python scripts/test_dspy_sandbox.py |
Sanity check the sandbox |
python scripts/debug_executor.py |
Integration test with mock client |
Execution Environment & Guardrails
By default, the system uses a Local Python Executor (LocalPythonExecutor) which runs code in the same process as the server. This is necessary because the strict Pyodide sandbox has limitations with network I/O, preventing it from calling back to other MCP tools in some environments.
Guardrails
Even with the local executor, the system enforces policies before code execution:
- Limits: 8k characters / 400 lines max.
- Imports: Allowlist only (
json,math,re,datetime, etc.). - Tokens: Disallows potentially dangerous tokens (
subprocess,exec,eval).
Violations return a POLICY_VIOLATION error.
Note: You can force the use of the Pyodide sandbox by setting
MCP_EXECUTOR=pyodide, but this may break tool calls depending on your environment.
Architecture
Overview
┌─────────────────────────────────────────────────────────────┐
│ MCP Client (Claude, etc.) │
└────────────────────────┬────────────────────────────────────┘
│ MCP Protocol (stdio/HTTP/SSE)
▼
┌─────────────────────────────────────────────────────────────┐
│ FastMCP Server │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ @mcp.tool │ │
│ │ async def execute_code(code: str): │ │
│ │ # 1. Execute in Local Executor (default) │ │
│ │ result = await executor.run(code) │ │
│ │ return result │ │
│ └──────────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌──────────────────────────────┐
│ Execution Engine: │
│ • LocalPythonExecutor │
│ (or Pyodide Sandbox) │
└──────────────────────────────┘
Why Code Mode?
Traditional MCP implementations face critical challenges:
- Context Window Bloat: Every tool definition consumes tokens, limiting scalability.
- Token Cost: Multiple back-and-forth tool calls are expensive.
- Latency: Sequential tool invocations create cumulative delays.
- Composability: Complex workflows require many discrete steps.
Code Mode addresses these by leveraging what LLMs excel at: writing code. Rather than making multiple tool calls, the agent writes a Python script that orchestrates all necessary operations internally.
Core Components
-
The Executor Server (FastMCP) (
src/mcp_code_mode/executor_server.py) The server exposes anexecute_codetool backed by a Python executor (Local or Pyodide). Usesfastmcpto handle the MCP protocol anddspyfor execution logic. -
Configuration-Driven Discovery (
mcp_servers.json) The system usesmcp_servers.jsonto explicitly configure which MCP servers to connect to. Loaded bysrc/mcp_code_mode/mcp_manager.py. -
Tool Schema Formatting (
src/mcp_code_mode/tool_formatter.py) Formats discovered MCP tools into readable documentation that gets passed to the code generation LLM, so it knows what tools exist. -
Context Injection The formatted tool schemas are passed as an input field to the LLM. The LLM knows tool names, parameters, and usage examples before it writes the code.
Information Flow
1. mcp_servers.json (Defines servers)
↓
2. MCPServerManager.initialize()
├─ Connect to configured servers
├─ Call list_tools() on each
└─ Convert to DSpy tools
↓
3. ToolSchemaFormatter.format_for_llm()
└─ Creates readable documentation
↓
4. CodeExecutionAgent
└─ Stores both callable tools and schemas
↓
5. Agent Generation
└─ Passes tool_context to LLM
↓
6. Code Execution
└─ Code runs in sandbox, calling actual tools via MCP
Troubleshooting
Timeout Issues: If the interpreter times out, it may enter a bad state. Currently, the best fix is to restart the server or reconnect the client to get a fresh interpreter instance.
Missing Tools:
Ensure mcp_servers.json paths are correct and that you have run npm install if using Node-based servers.
References
mcp-code-mode
Metadata
Release files for iflow-mcp_draphonix_mcp-code-mode 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_draphonix_mcp_code_mode-0.1.0.tar.gz | 25.2 kB | Without provenance | Details for iflow_mcp_draphonix_mcp_code_mode-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_draphonix_mcp_code_mode-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_draphonix_mcp_code_mode-0.1.0-py3-none-any.whl |
Total release size: 52.9 kB
Release files / iflow_mcp_draphonix_mcp_code_mode-0.1.0.tar.gz
| Download URL | iflow_mcp_draphonix_mcp_code_mode-0.1.0.tar.gz |
|---|---|
| Size | 25.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9142cfda9a999a2898e8bd3ec3661274ccd3fe1f9e3210765e90bea47b4386cc
|
|
BLAKE2b-256 checksum How to use checksums |
be923b80608f111875ccb43eff52085e268a9805aaa13200d4674276566022e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.28 {"installer":{"name":"uv","version":"0.9.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_draphonix_mcp_code_mode-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_draphonix_mcp_code_mode-0.1.0-py3-none-any.whl |
|---|---|
| Size | 27.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
00d62c44a0ed63ccd8610c2c65a0b7a43765cf7653e5a8818f64eb6bd3056bf2
|
|
BLAKE2b-256 checksum How to use checksums |
f688c8675f3e0bba755a21c146a557a96e905e649c2cf041e96c269a287fdc75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.28 {"installer":{"name":"uv","version":"0.9.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_draphonix_mcp-code-mode 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.