Code Execution MCP

Implements the patterns from Anthropic's "Code Execution with MCP" article for efficient AI agent operations.

Core Insight

Instead of loading thousands of tool definitions upfront and passing intermediate results through model context, agents write code that:

1. Discovers tools on-demand (progressive disclosure)
2. Processes data in a sandbox (not in context)
3. Returns only summarized/filtered results

Result: Up to 98.7% token reduction compared to direct tool invocation.

Features

1. Sandboxed Code Execution

• Resource limits (30s timeout, 500MB memory)
• Restricted builtins (safe subset)
• Safe modules (json, re, math, datetime, etc.)
• Workspace file utilities

2. Progressive Tool Discovery

• Search tools by query without loading definitions
• Get summaries first, full definitions on-demand
• Organized by category (security, memory, cluster, etc.)

3. PII Tokenization

• Auto-detect sensitive data (emails, phones, SSNs, etc.)
• Replace with tokens before data reaches model
• Restore when needed for tool calls

4. Skills Persistence

• Save reusable code snippets
• Build compound capabilities over time
• Share across sessions

Tools

Tool	Description
execute_code	Run Python in secure sandbox
search_tools	Progressive tool discovery
get_tool_definition	Load full tool details
save_skill	Persist reusable code
load_skill	Load saved skill
list_skills	List all skills
sanitize_pii	Tokenize PII in text
restore_pii	Restore tokenized PII
write_workspace_file	Persist data to workspace
read_workspace_file	Read from workspace
list_workspace_files	List workspace contents
get_execution_stats	Environment statistics

Usage Examples

Efficient Data Processing

# Instead of returning 10,000 rows to context:
code = '''
data = json.loads(read_file("large_dataset.json"))
filtered = [d for d in data if d['status'] == 'active']
result = {
    'total': len(data),
    'active': len(filtered),
    'sample': filtered[:5]
}
'''
execute_code(code)
# Returns only summary, not full dataset

Progressive Tool Discovery

# Find security tools (minimal tokens)
search_tools("vulnerability", category="security", detail_level="summary")

# Load full definition only when needed
get_tool_definition("web_vuln_scanner", category="security")

Privacy-Preserving Operations

# Sanitize before processing
sanitize_pii("Contact john@example.com at 555-123-4567")
# Returns: "Contact [EMAIL_abc123] at [PHONE_def456]"

# Restore when needed
restore_pii("[EMAIL_abc123]")
# Returns: "john@example.com"

Building Skills

# Save a reusable skill
save_skill(
    name="filter_high_risk",
    code="def filter_high_risk(vulns): return [v for v in vulns if v['severity'] in ['high', 'critical']]",
    description="Filter vulnerabilities to high/critical only"
)

# Use in future code execution
code = '''
skill = load_skill("filter_high_risk")
exec(skill)
vulns = json.loads(read_file("scan_results.json"))
result = filter_high_risk(vulns)
'''

Installation

cd /mnt/agentic-system/mcp-servers/code-execution-mcp
pip install -e .

Configuration

Add to ~/.claude.json:

{
  "mcpServers": {
    "code-execution": {
      "command": "/mnt/agentic-system/.venv/bin/python3",
      "args": ["/mnt/agentic-system/mcp-servers/code-execution-mcp/src/code_execution_mcp/server.py"],
      "disabled": false
    }
  }
}

Architecture

code-execution-mcp/
├── workspace/           # Sandboxed file storage
├── skills/              # Persistent skill definitions
├── tools_registry/      # Tool definitions for discovery
│   ├── security/        # Security tools
│   └── memory/          # Memory tools
└── src/
    └── code_execution_mcp/
        └── server.py    # Main MCP server

Security Notes

• Code runs with restricted builtins (no open, exec, eval on arbitrary input)
• File access limited to workspace directory
• Resource limits prevent runaway execution
• No network access from sandbox

References

• Anthropic: Code Execution with MCP
• Cloudflare: Code Mode Research