mcptoon — Two agent problems, one fix. Cut MCP token waste.

Q: What does demo need — and why Node.js?

demo boots the official everything reference server via npx — that package doesn't live inside mcptoon, so it needs Node.js and a first-run download. The testing path (quickstart → stats → manifest) is pure Python, no Node.

Q: Does it touch my client settings?

Scanning (quickstart) reads existing configs and writes only its own ~/.mcptoon/config.json — no edits to clients. Writing into clients is sync's job, and it only moves when you run it: it prints a report of what it wrote, supports a --dry preview, touches only the mcpServers key, and by default writes every detected client in one pass — name one with --agent to go narrower. Codex is the exception — it writes the project's AGENTS.md. Scope the escape hatch honestly: deleting ~/.mcptoon/ removes mcptoon's own config and cache, but entries sync already wrote stay in your clients until you remove them — the report says where.

Four steps: test first, then cut.

No wiring, no rewriting configs. Step 1 puts the package down, step 2 scans what you already have, step 3 tests your own machine, step 4 picks a tier and cuts.

Install

One command. Pure standard library, zero third-party dependencies, no daemon, no account.

pip install mcptoon

The repo also ships one-line scripts, install.sh / install.ps1. To be upfront: their last step runs quickstart right away — install, and config is written in the same breath. If you'd rather set your own pace, use pip and go one step at a time.

Scan & unify

Reads the MCP configs already on this machine — Claude Desktop, Cursor, Cline, Windsurf: four client families, their candidate config files — and unifies them into one ~/.mcptoon/config.json. This step writes mcptoon's own file; writing into your clients is sync's job, and sync only goes where you explicitly send it.

mcptoon quickstart

Test: your numbers

Reads your manifest and reports what it costs per turn — the number actually happening on your machine. Ours read 45 tools as of page build: 8,380 → 5,635 (saving 32.8%). Two disclaimers: the second line is the trimmed schema tier (descriptions truncated, types kept); and its ruler is a rough 4-chars≈1-token estimate — not the tiktoken yard the fixture is tested with. The two number-sets answer different questions; cross-multiplying them miscalculates.

mcptoon stats

Cut: two routes — know which one you're on

CLI route (deepest cut): the manifest ships names-only by default; before calling, mcptoon inspect <server> <tool> fetches that one tool's full arguments back; once you accept it, mcptoon sync writes into the client. Bridge route (for clients that must see an MCP server): mcptoon serve stands in front of your client and publishes the trimmed schema — what's saved is the fields layer. The OpenClaw pair below (−798 tokens) tests exactly this tier. The two routes keep separate books; the numbers don't transfer.

mcptoon manifest

Token math: a three-rung ladder, and where the numbers come from

Two levers: a public benchmark whose raw data you can read, and one command that tests your own machine.

Tool discovery −99.2%

255 tools · full JSON schemas (native) — baseline

71,929

255 tools · names + types (names and parameter types only)

71,929→8,282

255 tools · names-only (default: manifest with no flags)

71,929→581

Same curve, 50-tool scale

14,113→114

One more layer: change the notation, don't cut fields. The same manifest can be TOON-encoded: 47,438 (−34%) — every field kept, only the representation changes; it's an encoding variant, it doesn't stand on the ladder. The names+types tier looks roughly like search|query:s*|limit:n — star marks required, s is string, n is number. Compression tracks the rung: at the 50-tool scale it's still −99.2%; the tool count barely matters. Pick your rung by what your client needs to see.

Where these numbers come from. A 255-tool / 50-server reference fixture, counted with tiktoken cl100k_base; raw data is public in benchmark_data.json, method in tiktoken-benchmarks.md — re-runnable. Also disclosed: an earlier 91% figure came from a shorter-descriptions fixture and is retired from this page. mcptoon demo prints this table; it tests the fixture, not your machine — your machine belongs to mcptoon stats.

Three number-sets, three rulers, kept apart on purpose. ① Reference fixture: the public 255-tool / 50-server manifest, cl100k ruler. ② Our machine: the one that built this page — stats' rough ruler: 8,380 → 5,635 (as of page build); a review-machine re-test (cl100k ruler, same 45-tool cache): full 7,793 → names+types 711 → names-only 161. ③ Your machine: mcptoon stats, tested yourself.

Call results · optional

Call a tool with --toon and the result is re-encoded in TOON

per call, off by default

…same returned data, denser notation (lossless round-trip)

varies with payload

Default output

plain JSON

It stacks under the manifest savings and only fires when you ask: mcptoon call <server> <tool> --toon. Default output is JSON — ask for nothing and you save nothing; how much it saves varies with the shape of the returned data, so test it. One example the demo prints for its own call: same payload, 21 → 17 tokens — 19% fewer.

Not a compatibility list. A wiring diagram.

Two real agents on the machine that built this page are pointed at mcptoon serve. Their config, verbatim, and what actually happened.

OpenClaw — a tested A/B

In ~/.openclaw/openclaw.json, key mcp.servers.mcptoon:

{ "command": ".../mcptoon.exe", "args": ["serve"] }

Same session, same model, two calls six minutes apart, both returned the right payload:

echo server registered directly — input 43,448 tokens
Same echo server, bridged through mcptoon serve — input 42,650 tokens

798 fewer input tokens on the turn (as of page build) — for one trivial echo tool. This is the serve-bridge tier (lighter manifest fields), a different ledger from the −99.2% names-only rung; the saving grows with the number of tools you register. One pair, one model: a direction we tested, not a guarantee.

Hermes Agent — handshake log

In %LOCALAPPDATA%/hermes/config.yaml:

mcptoon:
  command: mcptoon

Its MCP stderr log holds the whole lifecycle:

starting MCP server 'mcptoon'
serve started — stdio bridge mode
Initialize from client: {'name': 'mcp'}
Client initialized notification received

Today that entry reads disabled in hermes mcp list. So the claim is narrow and true: it handshook there, and it is registered there — not that it is running there now.

What mcptoon writes to directly (mcptoon sync): Claude Desktop · Cursor · Cline · Windsurf · VS Code Copilot — Cursor gets the global ~/.cursor/mcp.json. One project-level exception: Codex, written into the project's AGENTS.md. Everything else that can launch a stdio MCP server — OpenClaw and Hermes included — connects through mcptoon serve: one entry, zero hand-written per-agent config.

Questions, answered shortly

MCP, in one sentence?

The Model Context Protocol — how AI clients attach external tools: files, search, databases, browsers. The catch: every tool you add ships its full description into the model's context before you've typed a word, and it re-ships every turn. That bill grows fast.

Will my configs get uploaded?

Scanning, merging and manifest generation all happen on your machine. Exactly one path touches the network: the demo command, which boots the official public reference server (everything) and pulls its code from npm — a public package; none of your config is in it. Want zero network requests: run mcptoon manifest --compact against your own servers (review-machine re-test on the cl100k ruler: 161 tokens of output covering all 45 tool names).

With names-only, what stops the model picking the wrong tool or guessing arguments?

This tier only changes how the discovery manifest ships; calls are untouched. The default (names-only) suits models that already know what they want; before acting, mcptoon inspect <server> <tool> fetches that one tool's full arguments, and you call once you've confirmed them. Need the client itself to see arguments? Step up to names+types (8,282 on the fixture, −88.5%) or full fields — all three rungs are just flags on mcptoon manifest. How deep you cut is your dial, not ours.

What does demo need — and why Node.js?

demo boots the official everything reference server via npx — that package doesn't live inside mcptoon, so it needs Node.js and a first-run download. The testing path (quickstart → stats → manifest) is pure Python, no Node.

Is that −99.2% my machine, or a marketing number?

It's the reference fixture's number — we'd rather you knew now than felt let down later. Your number comes from mcptoon stats: our machine read 45 tools, 8,380 → 5,635 (−32.8%, as of page build) — far from 99.2%, because that line tests the trimmed-schema tier with a rough ruler. Same machine, cl100k ruler, cut to the floor: the review machine read 7,793 → 161. Both numbers are real; they answer different questions — one is the ceiling the ladder reaches on the fixture, the other is one machine's current state. The raw data rows are committed in the repo, and the same test run exists at the 5- and 50-tool scales — you can see the shape of the curve, not a cherry-picked dot.

Does it touch my client settings?

Scanning (quickstart) reads existing configs and writes only its own ~/.mcptoon/config.json — no edits to clients. Writing into clients is sync's job, and it only moves when you run it: it prints a report of what it wrote, supports a --dry preview, touches only the mcpServers key, and by default writes every detected client in one pass — name one with --agent <client> to go narrower. Codex is the exception — it writes the project's AGENTS.md. Scope the escape hatch honestly: deleting ~/.mcptoon/ removes mcptoon's own config and cache, but entries sync already wrote stay in your clients until you remove them — the report says where.

Is it free?

Yes. Apache-2.0, open source. All the code is on GitHub, and mcptoon stats reads your own servers — so you never have to take anyone's word for your token bill. Including ours.

Two agent problems. mcptoon fixes both.

This isn't just us talking.