An open-source, agnostic implementation of the MCP Code Mode concept for sandbox environments.
Inspired by:
- Cloudflare's Code Mode - Converting MCP tools into TypeScript APIs
- Anthropic's Code Execution with MCP - Safe code execution patterns
Traditional MCP (Model Context Protocol) usage exposes tools directly to LLMs, requiring them to make explicit tool calls. However, as Cloudflare discovered, LLMs are better at writing code to call MCP than calling MCP directly.
- LLMs excel at writing code: They've been trained on millions of real-world TypeScript examples, but only synthetic tool-calling examples
- Handle more complex tools: When tools are presented as TypeScript APIs, LLMs can work with larger and more sophisticated tool sets
- Efficient multi-step operations: Instead of feeding each tool result back through the LLM context, LLMs can write code that chains multiple calls together
- Better reasoning: Writing code is a more natural problem-solving mode for LLMs than structured tool invocations
This library implements a sophisticated 6-step pipeline:
User Query → Pseudocode Plan → Tool Filtering → TypeScript Generation
→ Code Implementation → Compilation → Sandboxed Execution
The system uses three specialized LLMs:
- Strategy LLM: High-level planning and pseudocode generation (most capable model)
- Tiny LLM: Fast filtering through large tool catalogs (lightweight, fast model)
- Main LLM: Code generation and implementation (capable coding model)
- Generate Pseudocode (Strategy LLM): Creates a high-level execution plan
- Filter Tools (Tiny LLM): Intelligently selects relevant tools from potentially thousands of options
- Generate TypeScript Interfaces: Converts filtered MCP tools into TypeScript API definitions
- Implement Code (Main LLM): Writes actual TypeScript code using the generated APIs
- Verify Compilation: Ensures type safety before execution
- Execute in Sandbox: Runs the code in a secure, isolated environment
npm install mcp-codemodeimport { CodeModeMCP } from 'mcp-codemode';
import { OpenRouterClient } from 'mcp-codemode/model_clients';
import { ComposioProvider } from 'mcp-codemode/mcp_providers';
import { E2BRunEnvironment } from 'mcp-codemode/run_environments';
// Initialize OpenRouter client for LLM access
const openRouterClient = new OpenRouterClient();
// Setup Composio with your project
const composioProvider = new ComposioProvider({
projectId: 'your-project-id', // Optional: configure with connectedAccountId and userId
});
// Configure with three specialized LLMs
const codeMode = new CodeModeMCP({
llms: {
tinyLLM: openRouterClient.getLLM('openai/gpt-oss-20b'), // Fast filtering model
mainLLM: openRouterClient.getLLM('openai/gpt-oss-120b'), // Code generation model
strategyLLM: openRouterClient.getLLM('anthropic/claude-sonnet-4.5') // Strategic planning
},
tools: await composioProvider.getTools({
toolkits: ['slack', 'gmail', 'github'] // Specify the toolkits you need
}),
runEnvironment: new E2BRunEnvironment(), // Secure cloud sandbox
logPath: './prompt_logs' // Optional: log all LLM interactions
});
// Execute a complex multi-step task
const result = await codeMode.runMCPCode({
query: "get all channels from slack, and send a message to every channel that start with 'test', set an emoji on each message in channels that start with the letter 'e'",
maxToolCalls: 100,
totalExecutionTimeout: 60,
toolCallTimeout: 10
});
console.log(`Execution: ${result.resultType}`);
console.log(`Duration: ${result.totalDurationMs}ms`);With potentially thousands of tools available, the Tiny LLM rapidly filters down to only relevant tools, reducing context size and improving accuracy.
All generated code is TypeScript with full type checking before execution, catching errors early.
Supports multiple execution environments:
- Local: Node.js process isolation
- E2B: Cloud sandboxes for production use
- Custom: Implement your own
IRunEnvironment
- Detailed timing reports for each pipeline step
- Optional logging of all LLM prompts and responses
- Execution traces for debugging
- MCP Provider Agnostic: Works with Composio, Pipedream, or custom providers
- Model Agnostic: Use OpenAI, OpenRouter, or any LLM that follows the interface
- Environment Agnostic: Run locally or in the cloud
interface CodeModeMCPConfig {
llms: {
tinyLLM: LLMFunction; // Fast filtering model
mainLLM: LLMFunction; // Code generation model
strategyLLM: LLMFunction; // Planning model
};
tools?: ToolCatalog; // Hierarchical tool catalog
mcpProvider?: IMCPProvider; // Optional MCP provider
runEnvironment?: IRunEnvironment; // Execution sandbox
logPath?: string; // Optional logging directory
}interface RunMCPCodeOptions {
query?: string; // User task description
maxToolCalls: number; // Limit on tool invocations
totalExecutionTimeout: number; // Overall timeout (seconds)
toolCallTimeout: number; // Per-tool timeout (seconds)
maxToolsPerPrompt?: number; // Tools per filtering batch (default: 20)
maxConcurrentThreads?: number; // Parallel filtering threads (default: 5)
includeDescriptionsInFilter?: boolean; // Include tool descriptions in logs
}import { LLMFunction } from 'mcp-codemode/model_clients';
const myCustomLLM: LLMFunction = async (prompt: string): Promise<string> => {
// Your LLM integration here
const response = await myLLMService.complete(prompt);
return response.text;
};
const codeMode = new CodeModeMCP({
llms: {
strategyLLM: myCustomLLM,
tinyLLM: myCustomLLM,
mainLLM: myCustomLLM
},
// ... other config
});import { IRunEnvironment } from 'mcp-codemode/run_environments';
class MyCustomEnvironment implements IRunEnvironment {
async execute(code: string): Promise<{ success: boolean; output: string }> {
// Your execution logic
}
}// List all available tools
const toolPaths = codeMode.listToolPaths();
console.log(toolPaths); // ['slack.message.send', 'github.issues.create', ...]
// Get a specific tool
const tool = codeMode.getTool('slack.message.send');
// Update the catalog
codeMode.setToolCatalog(newCatalog);src/
├── CodeModeMCP.ts # Main orchestrator class
├── steps/ # Pipeline steps
│ ├── generatePseudocode.ts
│ ├── filterTools.ts
│ ├── generateToolsCode.ts
│ ├── implementCode.ts
│ └── executeCode.ts
├── model_clients/ # LLM integrations
│ ├── openai.ts
│ └── openrouter.ts
├── run_environments/ # Execution sandboxes
│ ├── local.ts
│ └── e2b.ts
└── mcp_providers/ # MCP server integrations
├── composio.ts
└── pipedream.ts
As MCP adoption grows, agents will have access to hundreds or thousands of tools. Traditional tool-calling approaches break down at scale:
- Context limits: Can't fit all tool definitions in a prompt
- Poor selection: LLMs struggle to choose the right tool from many options
- Inefficient chaining: Each tool result must round-trip through the LLM
Code Mode solves these problems by leveraging what LLMs do best: writing code. This library provides a production-ready implementation that's modular, extensible, and platform-agnostic.
This is a completely free and open-to-collaboration repository. Contributions are welcome!
- Report issues
- Submit pull requests
- Suggest improvements
- Share your use cases
MIT