Code Mode for MCP Servers

What is Code Mode?

When an MCP tool returns a large API response (e.g. listing 500 Kubernetes pods, 200 SCIM users, or thousands of GitHub issues), that entire payload enters the LLM's context window — consuming tokens and degrading performance.

Code mode flips the approach: instead of dumping raw data into context, the LLM writes a small processing script. The MCP server runs the script in a sandboxed runtime against the raw data, and only the script's stdout enters context.

This works especially well with well-known APIs (SCIM, Kubernetes, GitHub, Stripe, Slack, AWS, etc.) because the LLM already knows the response schema from training data — it can write the extraction script in one shot without inspecting the data.

Typical results: 65–99% context reduction.

Inspiration

• Cloudflare Code Mode
• claude-context-mode

---

How This Skill Works

This is an interactive planning skill. Work with the user step-by-step:

1. Understand their MCP server (language, framework, what tools return large data)
2. Select a sandbox that fits their server language and security needs
3. Plan the implementation together
4. Implement the code mode tool, sandbox executor, and benchmark
5. Verify with benchmarks comparing before/after context sizes

Do not jump ahead. Confirm each step with the user before proceeding.

---

Step 1: Understand the Existing MCP Server

Ask the user (or discover by reading their codebase):

• Server language: TypeScript/JavaScript, Python, Go, Rust, or other?
• MCP framework: XMCP, FastMCP, mcp-go, custom, etc.?
• Which tools return large responses? (e.g. list users, get pods, search issues)
• What APIs do they call? Well-known APIs (SCIM, K8s, GitHub, Stripe) are ideal candidates because the LLM already knows the schema.
• What languages should the sandbox support for script execution? Usually JavaScript is sufficient. Python is a common second choice.

Summarize your understanding back to the user and confirm before moving on.

---

Step 2: Select a Sandbox

The sandbox must be isolated from the host filesystem and network by default and secure by default. Present the user with options that match their server language, using the reference in references/sandbox-options.md.

Quick Selection Guide

If the server is TypeScript/JavaScript:

If the server is Python:

If the server is Go:

If the server is Rust:

Read references/sandbox-options.md for detailed tradeoffs on each option.

Present 2–3 options to the user (filtered to their server language), explain the tradeoffs briefly, and let them choose. If they're unsure, recommend the lightest WASM-based option for their language.

---

Step 3: Plan the Implementation

Once the sandbox is selected, create a concrete plan with the user. The plan should cover these components:

3a. Code Mode Tool

A new MCP tool (e.g. code_mode or <domain>_code_mode) that accepts:

• command or args: The underlying API call / query to execute (e.g. kubectl args, SCIM endpoint + params, GraphQL query)
• code: The processing script the LLM writes
• language (optional): Script language, defaults to javascript

The tool handler:

1. Executes the underlying API call (reusing existing logic)
2. Passes the raw response as a DATA variable into the sandbox
3. Runs the script in the sandbox
4. Returns only the script's stdout, plus a size measurement line: [code-mode: 18.0KB -> 6.2KB (65.5% reduction)]

3b. Sandbox Executor

A utility module that:

• Initializes the chosen sandbox runtime
• Injects DATA (the raw API response as a string) into the sandbox
• Executes the user-provided script
• Captures stdout and returns it
• Enforces a timeout (e.g. 10 seconds)
• Handles errors gracefully (script syntax errors, runtime errors)

3c. Wiring

• Register the new tool in the MCP server's tool list
• Optionally gate behind an env var (ask the user if they want this)

3d. Benchmark

A benchmark script that compares tool output size vs. code-mode output size across realistic scenarios. See references/benchmark-pattern.md for the template.

Present the plan to the user and confirm before implementing.

---

Step 4: Implement

Follow the confirmed plan. Implement in this order:

1. Install the sandbox dependency (e.g. npm i quickjs-emscripten)
2. Create the executor module — the sandbox wrapper
3. Create the code mode tool — the MCP tool handler
4. Wire it into the server — register the tool
5. Create the benchmark script

Keep the implementation minimal — don't over-abstract. The executor and tool can each be a single file.

Implementation Tips

• The DATA variable should always be a string (JSON-serialized). The script is responsible for parsing it if needed (JSON.parse(DATA) in JS, json.loads(DATA) in Python).
• Include the reduction measurement in every response so the user/LLM can see the savings: [code-mode: {before}KB -> {after}KB ({pct}% reduction)]
• Set a reasonable default timeout (10s) and memory limit if the sandbox supports it.
• Return clear error messages if the script fails — the LLM will use the error to fix its script on the next call.

---

Step 5: Benchmark and Verify

After implementation, run the benchmark to verify code mode actually reduces context size. Read references/benchmark-pattern.md for the full template.

The benchmark should:

1. Generate or fetch realistic test data — use faker/mock data if no live API is available, or hit a real endpoint if the user has one.
2. Run each scenario through both paths:
   • Regular tool response (full JSON)
   • Code mode with a representative extraction script
3. Print a comparison table showing before/after sizes and reduction %
4. Print a total across all scenarios

Present the benchmark results to the user. Typical expectations:

• Simple list extractions: 60–80% reduction
• Filtered queries (e.g. "only inactive users"): 90–99% reduction
• Aggregations (e.g. "count per department"): 95–99% reduction

---

Reference Files

• references/sandbox-options.md — Detailed comparison of all sandbox options by server language, with security analysis and setup instructions
• references/benchmark-pattern.md — Benchmark script template and methodology