OpenCodeMode (MCP)

Execute, filter, and orchestrate Model Context Protocol (MCP) tools inside an isolated, token-efficient sandbox in a single LLM turn.

Table of Contents

• Overview
• The Problem: Why Traditional MCP Breaks at Scale
• The Solution: OpenCodeMode Architecture
• End-to-End Request Flow
• Cloudflare Code Mode vs. OpenCodeMode
• Performance & Token Benchmark
• Installation & Quickstart
• Configuration: Connecting Your MCP Servers
  • Mode 1: Multi-Spoke Hub (codemode.config.json)
  • Mode 2: Instant Single-Server Wrapper (--wrap)
  • Mode 3: Embedded TypeScript Library
• How the LLM Orchestrates Tools in 1 Turn
• How to Connect to Any IDE or Agent
  • 1. Claude Desktop
  • 2. Cursor & Windsurf
  • 3. Google Antigravity & Gemini CLI
  • 4. VS Code (Cline / Roo Code)
  • 5. Custom Multi-Agent Frameworks (LangGraph, CrewAI, AutoGen)
• Security Model & Sandboxing
• Running Benchmarks & Automated Tests
• License

Overview

OpenCodeMode is an open-source, vendor-agnostic implementation of the Code Mode pattern for the Model Context Protocol (MCP).

Instead of forcing your AI Agent to execute individual JSON-RPC tool calls across multiple round-trips—flooding the context window with raw schemas and bloated intermediate responses—OpenCodeMode collapses all downstream tools into one single tool (execute_code).

The agent writes a concise TypeScript snippet against generated .d.ts definitions. That code executes inside a hardened, isolated sandbox (Deno or Node.js Worker), joins and filters data in memory, and returns only the final answer to the LLM in 1 single turn.

Deploy Anywhere: Designed for any platform—Cloud (AWS, GCP, Azure), On-Premises, Hybrid, Kubernetes, Docker, or local machines.

The Problem: Why Traditional MCP Breaks at Scale

When connecting enterprise agents to modern hubs (Jira, ServiceNow, GitHub, AWS, Postgres, Jenkins, etc.), standard MCP architectures hit three massive bottlenecks:

TRADITIONAL MCP: 7 TURNS, 4,344 TOKENS, 12.6 SECONDS
LLM  <-- (350 tokens of JSON schemas) -----------------------------> Agent
Turn 1: LLM calls db.list_users()     --> 100 raw JSON records (3,900 tokens) enters context!
Turn 2: LLM calls jira.get_issue(#1)  --> raw issue payload enters context
Turn 3: LLM calls jira.get_issue(#2)  --> raw issue payload enters context
...
Turn 7: LLM finally returns answer    --> 12.6s elapsed, context bloated, high API cost!

1. Schema Context Exhaustion: Dumps dozens or hundreds of JSON schemas into the system prompt on every request (costing 40,000 to 100,000+ tokens before the user even types a word).
2. Intermediate Data Pollution: In multi-step workflows, large intermediate payloads (e.g. 5 MB build logs, 500-row SQL dumps, raw API JSON) are echoed back and forth through the model context.
3. Turn-by-Turn Latency: 10 tool calls require 10 back-and-forth LLM inference round-trips (~30 to 60 seconds).
4. Tool Call Limit Crashing: LLMs routinely hit maximum step limits (e.g., 25–50 iterations) when doing repetitive loops or bulk processing.

The Solution: OpenCodeMode Architecture

OpenCodeMode sits as an intelligent gateway layer between the AI Agent and your MCP servers:

OPENCODEMODE: 1 TURN, 602 TOKENS, 1.8 SECONDS
LLM  <-- (250 tokens of compact .d.ts types) ------------------------> Agent
Turn 1: LLM writes ONE TypeScript script:
        "const users = await mcp.postgres.list_users();
         const target = users.filter(u => u.rating >= 4.7);
         for (const u of target) await mcp.bonus.award({ id: u.id });
         return target.map(u => u.name);"
               │
               ▼ (Executes locally in secure Sandbox in 40ms)
        Sandboxed RAM filters 100 records in memory.
        Downstream tools called via fast local IPC.
               │
               ▼
LLM  <-- Returns clean 3-line result array --------------------------> Done in 1 Turn!

End-to-End Request Flow

As shown in the architecture diagram, the lifecycle of a user request proceeds through these 15 steps:

[Developer/User] ──(1) Natural Language──► [Customer App / IDE]
                                                    │
                                         (2) HTTPS Request (AuthN/Rate Limit)
                                                    ▼
                                          [customer-api Gateway]
                                                    │
                                         (3) Forward Context & Task
                                                    ▼
                                         [coordinator-agent]
                                           │              │
                   (4) Request Plan / Code │              │ (6) Optional Specialist
                                           ▼              ▼     Agents (worklist, policy)
                                     [External LLM]       │ (7) Return Results
                                           │              │
                   (5) Plan / Code Script  │              ▼
                                           ▼     (8) Calls execute_code()
                                         [OPEN-CODE-MODE GATEWAY]
                                           │  ├── 1. Single Tool: execute_code()
                                           │  ├── 2. Isolated Sandbox (No Net/No ENV)
                                           │  └── 3. Routing & Tool Bridge
                                           │
                                         (9) Routes to Downstream Servers
                                           ▼
                    ┌──────────────────────┬──────────────────────┐
                    ▼                      ▼                      ▼
           [mcp-worklist-server]    [mcp-hr-server]       [mcp-email-server]
                    │                      │                      │
             (10) API Calls         (10) API Calls         (10) API Calls
                    ▼                      ▼                      ▼
             [Git / Worklist]        [HR System]            [Email System]
                    │                      │                      │
             (11) Raw Results Trapped in Sandbox RAM (Only Filtered Summary Returns)
                    │
                    ▼
          [coordinator-agent] ──(12) Final LLM Call──► [External LLM]
                    │                                         │
                    │ ◄───────────(13) Final Answer───────────┘
                    │
          (14) Stream Final Response
                    ▼
          [customer-api] ──(15) Stream Response to User──► [Developer / IDE]

1. User asks coding task: Request originates from Web UI, IDE, or chat app.
2. HTTPS Request: Passes through customer-api for authentication, rate limiting, and trace generation.
3. Forward Context: API sends user prompt and workspace context to the coordinator-agent.
4. Request Plan / Code: Coordinator calls the External LLM (Claude, GPT, Gemini).
5. LLM Returns Script: The LLM inspects compact .d.ts declarations and writes a single TypeScript orchestration snippet.
6. Optional Specialist Agents: If needed, coordinator queries domain specialist agents (worklist, policy, notification).
7. Specialists Return Results: Context is consolidated at the coordinator.
8. Calls execute_code: Coordinator invokes OpenCodeMode's execute_code tool with the snippet.
9. Spoke Routing: OpenCodeMode's IPC bridge routes tool calls to target MCP servers (Worklist, HR, Email).
10. Downstream Execution: MCP servers invoke external enterprise APIs and databases.
11. In-Memory Filtering: Thousands of raw JSON records are processed in sandbox RAM; only filtered results return.
12. Coordinator Calls LLM for Synthesis: Sends filtered observations to LLM for final formatting.
13. Final Answer: External LLM returns concise answer.
14. Coordinator Streams Response: Formatted output sent back to customer-api.
15. Delivery: Result streamed back to developer in 1 single conversational turn.

Cloudflare Code Mode vs. OpenCodeMode: What We Changed

The pioneering idea of "Code Mode" was published by Cloudflare's AI team and Cloudflare Agents.

While Cloudflare demonstrated the power of the concept, their implementation was designed specifically for Cloudflare's proprietary cloud ecosystem. OpenCodeMode is built from the ground up as a universal, self-hosted, enterprise-grade open-source solution:

Performance & Token Benchmark

We conducted a verified, reproducible benchmark comparing Traditional MCP tool calling against OpenCodeMode executing an audit over 100 customer records and triggering automated fraud flagging:

To run this benchmark live on your machine:

npm run benchmark

Installation & Quickstart

Prerequisites

• Node.js: v18.0.0 or higher (v20+ or v24 recommended)
• Optional (Recommended): Deno for OS-level subprocess sandboxing (OpenCodeMode automatically falls back to hardened Node Worker Threads if Deno is not installed).

1. Clone & Build

git clone https://github.com/your-org/open-codemode.git
cd open-codemode
npm install
npm run build

2. Verify Your Setup

# Run the 19 automated unit & integration test suites
npm test

# Run security sandbox regression attacks
npm run test:security

3. Docker Deployment (Optional)

You can also run OpenCodeMode as a hardened Docker container with bundled Deno sandbox isolation:

# Build the Docker image
docker build -t open-codemode-mcp .

# Run with your codemode.config.json mounted
docker run -i --rm -v $(pwd)/codemode.config.json:/app/codemode.config.json open-codemode-mcp

Configuration: Connecting Your MCP Servers

OpenCodeMode works with any MCP server. You don't need to write code to connect your tools—just specify them using one of the three modes below.

Mode 1: Multi-Spoke Hub (codemode.config.json)

Connect multiple MCP servers (Jira, GitHub, Postgres, AWS, ServiceNow) simultaneously into a unified sandbox.

Generate a starter configuration file:

node dist/cli.js --init

Or create codemode.config.json in your project root:

{
  "$schema": "https://json.schemastore.org/mcp-config.json",
  "mcpServers": {
    "jira": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "JIRA_API_TOKEN", "mcp/jira"],
      "env": {
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://${DB_USER}:${DB_PASS}@localhost:5432/mydb"
      ]
    },
    "aws": {
      "command": "python",
      "args": ["-m", "mcp_server_aws"]
    }
  },
  "executionOptions": {
    "timeoutMs": 15000,
    "memoryLimitMb": 128
  }
}

Then run OpenCodeMode:

# Auto-loads codemode.config.json in the current working directory
node dist/cli.js

# Or specify a custom config file path
node dist/cli.js --config /path/to/my-config.json

Security Note: Environment variables (like ${GITHUB_TOKEN}) are expanded at runtime on the host machine. No credentials are ever passed into the sandbox.

Mode 2: Instant Single-Server Wrapper (--wrap)

If you just want to wrap a single MCP server on the fly without creating a configuration file:

# Wrap a PostgreSQL MCP server
node dist/cli.js --wrap "npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb"

# Wrap an in-memory MCP server
node dist/cli.js --wrap "npx -y @modelcontextprotocol/server-memory"

# Wrap a custom Python MCP server
node dist/cli.js --wrap "python -m my_mcp_server"

Mode 3: Embedded TypeScript Library

You can import OpenCodeMode directly into your own TypeScript / JavaScript agent backend:

import { CodeModeServer, DownstreamClient, MultiDownstreamClient } from "open-codemode";

// Connect to downstream spokes
const downstream = new MultiDownstreamClient({
  jira: { command: "docker", args: ["run", "-i", "--rm", "mcp/jira"] },
  github: { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] }
});
await downstream.connect();

// Create upstream Code Mode server
const server = new CodeModeServer({
  downstreamClient: downstream,
  executionOptions: { timeoutMs: 15000, memoryLimitMb: 128 }
});

await server.start();

How the LLM Orchestrates Tools in 1 Turn

When the AI Agent connects to OpenCodeMode, it receives a single tool: execute_code. All tools from your configured servers are automatically compiled into clean TypeScript namespaces:

declare namespace mcp {
  namespace jira {
    /** Search Jira tickets with JQL */
    function search_issues(args: { jql: string }): Promise<any>;
    /** Update issue status */
    function update_issue(args: { id: string; status: string }): Promise<any>;
  }

  namespace github {
    /** Get pull request details */
    function get_pr(args: { prNumber: number }): Promise<any>;
  }

  namespace postgres {
    /** Execute SQL query */
    function query(args: { sql: string }): Promise<any>;
  }
}

The LLM writes standard async TypeScript to orchestrate across spokes:

// Script written by the LLM:
const openTickets = await mcp.jira.search_issues({ jql: "status = 'Review' AND priority = 'High'" });

const results = [];
for (const ticket of openTickets) {
  // Query downstream GitHub spoke
  const pr = await mcp.github.get_pr({ prNumber: ticket.pr_id });
  
  // In-memory logic: only act if PR is approved and merged
  if (pr.merged) {
    await mcp.jira.update_issue({ id: ticket.id, status: "Done" });
    results.push({ ticket: ticket.key, title: ticket.summary, pr: pr.title });
  }
}

// Return only the clean, final report
return results;

How to Connect to Any IDE or Agent

OpenCodeMode runs as a standard MCP server communicating over stdio. It can be added to any MCP-compliant tool or agent in seconds.

1. Claude Desktop

Add to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "opencode-hub": {
      "command": "node",
      "args": [
        "C:/path/to/open-codemode/dist/cli.js",
        "--config",
        "C:/path/to/open-codemode/codemode.config.json"
      ]
    }
  }
}

2. Cursor & Windsurf

Add to .cursor/mcp.json in your workspace or global settings:

{
  "mcpServers": {
    "opencode-hub": {
      "command": "node",
      "args": [
        "/path/to/open-codemode/dist/cli.js",
        "--config",
        "/path/to/open-codemode/codemode.config.json"
      ]
    }
  }
}

3. Google Antigravity & Gemini CLI

Add to mcp_config.json:

{
  "mcpServers": {
    "open-codemode": {
      "command": "node",
      "args": [
        "/path/to/open-codemode/dist/cli.js",
        "--config",
        "/path/to/open-codemode/codemode.config.json"
      ]
    }
  }
}

4. VS Code (Cline / Roo Code)

In your Cline / Roo Code MCP Settings:

{
  "mcpServers": {
    "opencode": {
      "command": "node",
      "args": [
        "/path/to/open-codemode/dist/cli.js",
        "--config",
        "/path/to/open-codemode/codemode.config.json"
      ]
    }
  }
}

5. Custom Multi-Agent Frameworks (LangGraph, CrewAI, AutoGen)

Connect any agent worker via stdio or import OpenCodeMode as a Node.js library directly into your agent runner:

# Python LangGraph / CrewAI example invoking OpenCodeMode CLI over stdio:
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="node",
    args=["/path/to/open-codemode/dist/cli.js", "--config", "/path/to/codemode.config.json"]
)

Security Model & Sandboxing

Because OpenCodeMode executes LLM-generated code, security and isolation are primary engineering requirements.

+-------------------------------------------------------------+
| HOST PROCESS (Node.js)                                      |
| * Stores API keys, database credentials, host tokens        |
| * Speaks to upstream Agent and downstream MCP servers       |
| * Validates & sanitizes all IPC messages                    |
+------------------------------+------------------------------+
                               | IPC Channel (Line JSON-RPC)
                               v
+-------------------------------------------------------------+
| HARDENED SANDBOX (Deno / Worker)                            |
| 🔒 NO NETWORK:      --no-net (cannot make outbound fetch)   |
| 🔒 NO FILESYSTEM:   --no-read --no-write (cannot read disk) |
| 🔒 NO ENV SECRETS:  --no-env (cannot read process.env)      |
| 🔒 MEMORY CEILING:  128 MB max V8 heap space                |
| 🔒 HARD WATCHDOG:   15,000 ms kill timer terminates hangs   |
+-------------------------------------------------------------+

Running Benchmarks & Automated Tests

OpenCodeMode enforces strict testing standards:

# 1. Run all unit & integration test suites
npm test

# 2. Run security boundary & attack tests
npm run test:security

# 3. Run the head-to-head performance benchmark
npm run benchmark

# 4. Run vulnerability scan (Guaranteed 0 CVEs)
npm audit

Test Suite Summary:

▶ OpenCodeMode End-to-End Integration (2 tests)
▶ IpcBridge (3 tests)
▶ Multi-Spoke Configuration & Loading (2 tests)
▶ Multi-Spoke Type Generator (1 test)
▶ MultiDownstreamClient & Sandbox Execution (2 tests)
▶ Sandbox Security & Execution Tests (6 tests)
▶ TypeGenerator (3 tests)

✔ 19 tests passed, 0 failed (1.8s)
✔ 0 vulnerabilities found

License

This project is licensed under the MIT License. Feel free to use it in your commercial or open-source AI agent applications.