code2mcp - Code Mode MCP Server

Execute TypeScript code to call MCP tools instead of using direct tool calls. Based on Cloudflare's revolutionary Code Mode pattern.

What is Code Mode?

Instead of exposing MCP tools directly to the LLM (which wastes tokens and struggles with complex tools), Code Mode:

Converts MCP tools into TypeScript APIs with full type definitions
Has the LLM write code that calls those APIs
Executes code in a secure sandbox with access only to specified MCP servers
Returns only the final results to the LLM, not intermediate data

Benefits

✅ 98% token reduction for complex multi-tool workflows
✅ Better tool understanding: LLMs are trained on millions of TypeScript examples
✅ Handle complex tools: Full APIs vs simplified tool schemas
✅ Secure execution: Sandboxed code, no network/filesystem access
✅ API keys hidden: Keys stored in orchestrator, never exposed to LLM

Installation

# Clone or create project npm install # Build (TypeScript compilation only) npm run build # Build with API generation (recommended for first-time setup) npm run build:full

Note: build:full generates TypeScript API files from your MCP servers, which helps Claude understand parameter names and types. See IMPROVEMENTS.md for details.

Configuration

1. Pre-Configured MCP Servers ✅

Already configured and ready to use! Five MCP servers are pre-configured:

Context7 - Data storage and context management
Playwright - Browser automation and web scraping
Bright Data - Proxy network and geo-distributed scraping
Chrome DevTools - Chrome DevTools Protocol integration
Firecrawl - Advanced web crawling and content extraction

See CONFIGURED_SERVERS.md for details on each server.

To add more servers, edit src/index.ts and modify the MCP_SERVERS array:

const MCP_SERVERS: MCPServerConfig[] = [ // ... existing 5 servers ... { name: 'your-server', transport: 'stdio', command: 'npx', args: ['your-mcp-package'], env: {}, }, ];

2. Set Environment Variables

cp .env.example .env # Edit .env with your API keys

3. Register with Claude Code

Add to ~/.claude.json:

{ "mcpServers": { "code2mcp": { "command": "node", "args": ["/absolute/path/to/code2mcp/build/index.js"], "env": { "LOG_LEVEL": "info", "WEATHER_API_KEY": "your_key_here" } } } }

Usage

Example 1: Simple Tool Call

User: "What's the weather?"

Claude writes:

const weather = await __mcp_call('weather__get_current', { city: 'San Francisco' }); console.log(`Temperature: ${weather.temperature}°F`);

Output:

=== Execution Logs === Temperature: 65°F === Result === (undefined) Execution time: 234ms

Example 2: Multi-Step Workflow (Token Savings!)

User: "Get my Google Doc and update Salesforce"

Claude writes:

// Fetch document (potentially 50,000 tokens) const doc = await __mcp_call('google_drive__get_document', { documentId: 'abc123' }); // Update Salesforce (large document stays in sandbox!) await __mcp_call('salesforce__update_record', { objectType: 'Lead', recordId: 'xyz789', data: { Notes: doc.content // 50K tokens never enter Claude's context! } }); console.log('Updated Salesforce with document content');

Key Benefit: The 50,000-token document never enters Claude's context. Only the logs are returned!

Example 3: Complex Orchestration

// Get all files modified in last week const files = await __mcp_call('google_drive__list_files', { modifiedAfter: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString() }); console.log(`Found ${files.length} files`); // Process each file for (const file of files) { const doc = await __mcp_call('google_drive__get_document', { documentId: file.id }); // Analyze sentiment (simple keyword matching) const sentiment = analyzeSentiment(doc.content); console.log(`${file.title}: ${sentiment}`); } function analyzeSentiment(text) { const positive = (text.match(/great|excellent|success/gi) || []).length; const negative = (text.match(/issue|problem|failure/gi) || []).length; return positive - negative; }

This kind of complex orchestration would be impossible with standard MCP tool calling!

Architecture

┌─────────────────────────────────────┐ │ Claude Code (MCP Client) │ │ Sees: ONE tool (execute_code) │ └──────────────┬──────────────────────┘ │ Writes TypeScript code ▼ ┌──────────────────────────────────┐ │ code2mcp Server │ │ - Compiles TypeScript │ │ - Executes in Node.js VM │ │ - Injects __mcp_call binding │ └──────────────┬───────────────────┘ │ Routes tool calls ▼ ┌──────────────────────────────────┐ │ MCP Orchestrator │ │ - Manages MCP server conns │ │ - Stores API keys │ │ - Routes to correct server │ └──────────────┬───────────────────┘ │ ┌─────────┴─────────┬──────────┐ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ Google │ │Salesforce│ │ Weather │ │ Drive │ │ │ │ MCP │ │ MCP │ │ MCP │ │ │ └─────────┘ └──────────┘ └─────────┘

Development

# Development mode with hot reload npm run dev # Build npm run build # Test with MCP Inspector npm run inspector # Generate TypeScript APIs manually npm run generate-apis

Security

The sandbox provides basic isolation:

✅ No network access (fetch, XMLHttpRequest, WebSocket blocked)
✅ No filesystem access (fs, path blocked)
✅ No process access (child_process, process blocked)
✅ Only __mcp_call() binding available
✅ API keys stored in orchestrator, never in sandbox
✅ Timeout enforcement (default 30s)

Note: This uses Node.js built-in vm module, which provides basic isolation but is not as secure as isolated-vm or Deno. For production use, consider:

Using Deno with strict permissions
Using isolated-vm with older Node.js version (v20)
Running in a containerized environment
Deploying to Cloudflare Workers (best isolation)

Token Usage Comparison

Standard MCP (Direct Tool Calling)

Tool definitions: 10K tokens (50 tools × 200 tokens) Intermediate results: 40K tokens (large documents) Conversation: 50K tokens ──────────────────────────────────────────────── Total: ~100K tokens

Code Mode

Code written by LLM: 2K tokens Execution logs: 1K tokens Conversation: 50K tokens ──────────────────────────────────────────────── Total: ~53K tokens

Token Reduction: 47% for simple workflows, 98% for complex workflows!

Documentation

See /DOCS folder for complete architecture documentation:

DOCS/Architecture/SYSTEM_MAP.md - Complete architecture overview
DOCS/Architecture/CODE_STRUCTURE.md - File organization
DOCS/Etc/CODE_MODE_IMPLEMENTATION_PLAN.md - Detailed implementation plan

References

License

ISC

Contributing

Contributions welcome! This is a reference implementation of the Code Mode pattern.

Roadmap

Configuration file support (vs hardcoded in src/index.ts)
Deno sandbox implementation for better security
TypeScript API browser/explorer
Support for HTTP/WebSocket MCP transports
Streaming execution logs
Code templates library
Performance optimizations
Comprehensive test suite

Built with ❤️ implementing Cloudflare's Code Mode pattern

code2mcp