Code Executor MCP

One MCP to orchestrate them all. Progressive disclosure pattern - 98% token savings vs exposing all tools.

Based on Anthropic's Code Execution with MCP Built for Claude Code. Untested on other MCP clients.

Problem

47 MCP tools = 141k tokens just for schemas. Context exhausted before you start working.

Solution

Disable all MCPs. Enable only code-executor.

2 tools (executeTypescript, executePython) access all other MCPs on-demand:

// Claude writes this to access zen MCP
const result = await callMCPTool('mcp__zen__codereview', {...});

Result: 47 tools → 2 tools = 141k tokens → 1.6k tokens (98% reduction)

When to Use

✅ Use if:

• 3+ MCP servers (context bloat problem)
• Mix of local + remote + APIs
• Need audit logs, allowlisting, rate limiting

❌ Skip if:

• 1-2 MCPs (just enable them directly)
• Simple filesystem/git ops (use Node.js directly)

Wrappers (Optional)

Auto-discover tool parameters from MCP schemas:

npm run generate-wrappers  # Queries MCPs, generates ~/.code-executor/wrappers/*.ts

// Before: Blind guessing
await callMCPTool('mcp__zen__thinkdeep', {...}); // What params?

// After: TypeScript-enforced parameters (auto-discovered from schema)
await thinkdeep(step, step_number, total_steps, ...)

Wrappers are auto-generated from tools/list schemas, not manually written.

Validation

Deep recursive validation with AJV (JSON Schema library):

All MCP tool calls are validated against live schemas before execution using industry-standard AJV validator. Validates nested objects, arrays, constraints, enums, and patterns. If parameters are invalid, you get a detailed error explaining what's wrong:

Parameter validation failed for "mcp__zen__consensus"

Errors:
  - Missing required parameters: models
  - Unexpected parameters: model

Expected parameters:
  Required:
    • prompt: string - The prompt to analyze
    • models: array<string> - List of model IDs
  Optional:
    • temperature: number - Sampling temperature

You provided:
  { "prompt": "...", "model": "gpt-4" }

Benefits:

• 🎯 Catch errors before MCP call (faster feedback)
• 📚 See expected schema on failure (self-documenting)
• 🔒 Zero token overhead (validation server-side, schemas disk-cached)
• 🔐 Deep validation (nested objects, arrays, min/max, patterns, enums)
• ⚡ Mutex-locked disk cache (no race conditions, survives restarts)

Features

• Executors: TypeScript (Deno), Python
• Security: Sandboxed, allowlist, audit logs, rate limiting
• Validation: AJV-based deep validation, disk-cached schemas, mutex-locked
• Config: Auto-discovery, env vars, MCP integration
• Quality: TypeScript, 139 tests, 98%+ coverage on validation

Installation

# NPM
npm install -g code-executor-mcp
code-executor-mcp

# Or local dev
git clone https://github.com/aberemia24/code-executor-MCP.git
cd code-executor-mcp
npm install && npm run build
npm run server

# Docker (production)
docker-compose up -d

See DOCKER_TESTING.md for Docker security details.

Configuration

Add to .mcp.json:

{
  "mcpServers": {
    "code-executor": {
      "command": "node",
      "args": ["/path/to/code-executor-mcp/dist/index.js"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/.mcp.json"
      }
    }
  }
}

Then disable all other MCPs. Enable only code-executor.

License

MIT

---

Full docs: GitHub