Skip to main content
Glama
README.md
# mcp-code-mode

Code mode for any remote MCP server, after Cloudflare's
["Code Mode"](https://blog.cloudflare.com/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.

```js
// 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

```sh
# 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:

```js
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

```sh
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.

## 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

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

## License

MIT