Skip to main content
Glama

mcp-code-mode

Code mode for any remote MCP server, after Cloudflare's "Code Mode" idea.

An agent that uses MCP tools one by one pays a full model round trip per call, and every raw result lands in its context. Reading 27 chat channels means 28 tool calls and about 20,000 characters the model did not need.

mcp-code-mode sits between the agent and a remote MCP server and gives the agent one tool: run(code). The agent writes a short JavaScript script. The script calls the server's tools (in parallel if it likes), filters the data, and returns only the answer.

// one run() call instead of 28 tool calls
const { channels } = await chat.list_channels({ limit: 50 });
const convs = await Promise.all(channels.map(c => chat.read_conversation({ channel_id: c.id, limit: 20 })));
return channels
  .map((c, i) => ({ name: c.name, unanswered: convs[i].messages.filter(m => m.text.includes('?')).length }))
  .filter(c => c.unanswered > 0);

The run tool's description lists every remote tool as a typed function, built from the server's live tools/list. So the agent knows what it can call without any extra round trip.

  • Works with any MCP server over Streamable HTTP.

  • OAuth sign-in with dynamic client registration and PKCE, a static bearer token, or custom headers.

  • Read-only by default. You choose which tools count as read-only.

  • Plain Node 22+, no dependencies.

Quick start

# 1. See what the server offers and how each tool is classified
npx -y github:saurabhrkp-fiftyfive/mcp-code-mode tools --url https://mcp.deepwiki.com/mcp

# 2. Add it to Claude Code (any MCP client that runs stdio servers works)
claude mcp add deepwiki-code -s user -- npx -y github:saurabhrkp-fiftyfive/mcp-code-mode serve \
  --url https://mcp.deepwiki.com/mcp --name dw \
  --read-only read_wiki_structure,read_wiki_contents,ask_wiki_question

The agent now has mcp__deepwiki-code__run. It writes code such as:

const repos = ['modelcontextprotocol/typescript-sdk', 'cloudflare/agents'];
const pages = await Promise.all(repos.map(repoName => dw.read_wiki_structure({ repoName })));
return pages.map(p => p.result.split('\n').slice(0, 5));

Servers that need sign-in

npx -y github:saurabhrkp-fiftyfive/mcp-code-mode login --url https://mcp.example.com/mcp
npx -y github:saurabhrkp-fiftyfive/mcp-code-mode login --url https://mcp.example.com/mcp --scope "read write"

login finds the auth server from the MCP server's metadata (RFC 9728, then RFC 8414 or OpenID), registers its own client (RFC 7591), opens the browser and saves the token to ~/.config/mcp-code-mode/tokens/<host>_<path>.json (mode 600). It refreshes the token itself. For a server without dynamic registration, pass --client-id. For API-key servers, use --token or --header "X-Api-Key: …" instead.

Related MCP server: pi-code-mode-mcp

Commands and options

mcp-code-mode <serve|login|status|tools|run FILE> --url <mcp-url> [options]

Option

Env var

Meaning

--url URL

MCP_URL

Remote MCP endpoint. Required.

--name NAME

MCP_NAME

Name of the object scripts use. Default mcp.

--read-only a,b,c

MCP_READ_ONLY

Tools allowed in read-only mode.

--trust-hints

MCP_TRUST_HINTS=1

Also allow tools the server marks readOnlyHint: true.

--write

MCP_WRITE=1

Allow every tool, including writes.

--header "K: V"

MCP_HEADERS (JSON)

Extra HTTP header. Repeatable.

--token TOKEN

MCP_TOKEN

Static bearer token instead of OAuth.

--scope "a b"

MCP_SCOPE

OAuth scope to ask for at login.

--client-id ID

MCP_CLIENT_ID

OAuth client id for servers without dynamic registration.

tools prints each tool as read or write under your options, so you can check the list before you connect an agent. run FILE runs a script once from the shell, which is handy for testing.

How it works

agent ──run(code)──▶ mcp-code-mode (stdio MCP server, holds the token)
                         │ fork: node --permission, empty env, no token
                         ▼
                     sandbox child: vm context with only <name>.*, console, sleep
                         │ each <name>.tool(args) = IPC message to the parent
                         ▼
                     parent checks the tool is allowed, then calls the remote server over HTTP
  • Each run starts a fresh child process with Node's permission model: no file reads except the runner script, no child processes, no workers, an empty environment and a 256 MB heap.

  • The script runs in a vm context with no require, import, process, fetch or eval.

  • The child never sees the token. The parent makes every HTTP call and enforces the tool policy.

  • Limits per run: 120 s by default (max 300 s), 200 tool calls, 6 at a time, 4 MB per server reply, 20,000 log characters, 60,000 return-value characters, 40,000 characters of output.

Safety

  • Read-only by default, and you decide what read-only means. A tool is allowed only if it is on --read-only, or if you pass --trust-hints and the server marks it readOnlyHint: true. With neither, every tool is blocked until you pass --write. A new tool the server adds later stays blocked.

  • --write lets scripts do anything the account can do. Use it only for servers and accounts you would let the agent use directly.

  • Tool results and tool descriptions come from the remote server. Treat them as data, not as instructions.

  • The sandbox is defence in depth, not a hard security boundary. Node has no network permission flag yet, so code that escapes the vm context could reach the network. It would still have no token, no environment and no file access.

  • Several agent sessions can share one login: refresh runs under a lockfile.

Develop

git clone https://github.com/saurabhrkp-fiftyfive/mcp-code-mode && cd mcp-code-mode
npm test

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP extension that allows coding agents to manage and compose MCP tools by executing JavaScript in a sandboxed environment. It features tools for listing available MCP capabilities and a management command for handling authentication and tool policies.
      40
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to use many MCP servers without context bloat by exposing meta-tools (search, load, call, run_code) that reduce token usage via progressive disclosure and result trimming.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes a single execute tool so agents can discover, inspect schemas for, and compose calls to connected upstream MCP servers by writing JavaScript that runs in a fresh sandboxed QuickJS VM. Results from combined tool calls are returned as text or JSON, keeping large tool catalogs out of the agent's context.
      MIT