# Wrap MCP servers

> tokenade mcp-wrap routes third-party MCP servers through Tokenade, which compacts their tool results and shrinks large screenshots.

Source: https://tokenade.net/en/docs/mcp-wrap · Updated: 2026-10-07

`tokenade mcp-wrap` puts Tokenade between your agent and each third-party MCP server. The server runs exactly as before; Tokenade compacts the tool results it sends back, and shrinks screenshots that are larger than needed. Every tool stays available: wrapping changes what results cost, not which tools the agent sees. `tokenade install` sets this up for every agent it configures, so you rarely run it by hand.

## Usage

```text
tokenade mcp-wrap install [<server>]   # route configured MCP server(s) through the proxy (no name = all)
tokenade mcp-wrap uninstall [<server>] # restore original launch command (no name / --all = every wrapped)
tokenade mcp-wrap report               # per-tool savings table (+ real $)
tokenade mcp-wrap -- <bin> [<args>…]   # run as the proxy (agents do this)
tokenade mcp-wrap <bin> [<args>…]      # leading `--` is optional
```

Aliases: `mcp_wrap`, `mcp-proxy`, `mcp_proxy`. `mcp-proxy` is the former name, kept because existing configs still launch it.

## What happens to a tool call

1. Your agent launches `tokenade mcp-wrap -- <original command>` instead of the server.
2. Tokenade starts the real server and relays requests to it unchanged.
3. Each text item of a tool result is compacted. Known servers get a dedicated compactor, chosen from the server's own name: GitHub and GitLab API responses lose their URL and metadata noise, database query results become compact rows, the filesystem server's `directory_tree` becomes an indented tree, and browser servers (Playwright, Chrome) get their console logs and page content folded. Anything else goes through the same auto-detecting compactor as [`tokenade read`](https://tokenade.net/en/docs/compaction). Screenshot results are left as they are.
4. A result still larger than about 25k tokens after that (the file-read threshold, `TOKENADE_READ_DISCLOSE_THRESHOLD`, since your agent asked for that content) is written to the [stash](https://tokenade.net/en/docs/compaction) and replaced with a summary. The agent can drill in with `tokenade expand-ref <hash>`. Credentials are masked in every result.
5. Image results whose long edge is over the cap are resized and re-encoded. The payload is swapped only if it actually shrank, and a text item is appended saying the new size and how to turn it off.

One proxy runs per server per agent session, and it exits when the agent closes its stdin.

To keep screenshots at full resolution, set `TOKENADE_IMAGE_MAX_EDGE=0` in the wrapped server's environment.

## The tool list

The server's `tools/list` reply passes through with every tool kept. Tokenade only removes the inert keywords from each input schema (`title`, `$comment`, `examples`, `markdownDescription`), which never tell the agent how to call a tool. Per-parameter `description` fields are kept by default, because about one in five states a constraint nothing else in the schema expresses. Set `TOKENADE_MCP_LEAN_SCHEMA=1` to strip them as well, for a much smaller tool list at that risk.

Tokenade does not load tools lazily: the agent sees the same tools as without the wrapper. Agents that defer tool definitions (Claude Code's tool search, for example) keep doing so.

## install and uninstall

`install` and `uninstall` edit your agents' MCP configuration in place: Claude, Cursor, Codex, Copilot, Windsurf, Cline and VS Code, on Linux, macOS and Windows paths. They write a timestamped `.bak` first, rewrite atomically, and are idempotent and fully reversible.

```bash
tokenade mcp-wrap install            # wrap every configured third-party server
tokenade mcp-wrap install github     # wrap one server by name
tokenade mcp-wrap uninstall github   # restore that one
```

Servers that belong to an app's own installation (for example the browser and computer-use server the Codex desktop app adds) are left alone, because the app changes their path on every update.

Savings from desktop apps are credited to the app: each wrapped server carries the app's name, so Claude Desktop, the Codex app or Cursor show up under their own name in the dashboard.

### Claude Desktop Chat

Chat in Claude Desktop runs no local commands or file reads, so MCP optimisation is the only part of Tokenade that applies to it. Run `tokenade mcp-wrap install` to wrap the servers in its config. The Code tab of Claude Desktop is Claude Code and gets the full hook set; see [Claude Code](https://tokenade.net/en/docs/claude-code).

## report

```text
$ tokenade mcp-wrap report
No wrapped-MCP tool activity recorded yet. Wrap a server with `tokenade mcp-wrap install <server>` and use it, then re-run.
```

Once wrapped servers have been used, `report` prints savings per tool, priced at the same per-model rates as [`tokenade dashboard`](https://tokenade.net/en/docs/gain-dashboard-receipt).

## Check and undo

```bash
tokenade healthcheck           # lists each wrapped entry and the original it wraps
tokenade unwrap-mcps --dry-run # show which configs would be restored
tokenade unwrap-mcps           # flip every wrapped entry back
```

`unwrap-mcps` walks every known agent config and rewrites each wrapped entry back to its original `command` and `args`. It is idempotent and leaves the rest of Tokenade (hooks, rules, binary) in place. `tokenade uninstall` runs the same pass first, then removes everything else.

To keep `tokenade install` from wrapping servers in the first place, pass `--no-wrap-mcps`.

## Gotchas

- `healthcheck` reports wrapped entries that point at an old binary path (`wrapped_mcps`). Re-run `tokenade install` or `tokenade mcp-wrap install` to fix them.
- Large results are replaced by a summary plus a hash, not dropped. If your agent needs a detail, it asks the stash with `expand-ref`.
- On Claude Code, MCP results are also folded by a PostToolUse hook, which you can turn off with `TOKENADE_NO_MCP_HOOK=1`.

## Related

- [Get folded output back](https://tokenade.net/en/docs/expand-ref-disclose)
- [The LLM proxy](https://tokenade.net/en/docs/llm-proxy)
- [How hooks intercept tool calls](https://tokenade.net/en/docs/hooks)
- [Maintenance commands](https://tokenade.net/en/docs/maintenance)
