mcptoon MCP server

https://github.com/user-attachments/assets/0272d3a8-c74f-428d-8559-fbf804ce0685

---

🚀 Quick Start (Choose Your Way)

When installed, mcptoon automatically injects its own official skill (/mcptoon) into your agents. You never need to memorize terminal commands — just ask directly in Cursor, Claude Code, Windsurf, or DSH:

# Ask the built-in skill anytime:
"Load /mcptoon skill and check what MCP tools I currently have."
"Help me find an MCP tool that converts HTML to PDF and call it."
"The tool output was truncated, retrieve the full original copy."
"How many tokens did mcptoon save for me today?"
"Doctor self-check: are all my MCP servers connected properly?"

Your agent loads /mcptoon and drives everything behind the scenes!

# 1. Install (zero dependencies, 565KB)
pip install mcptoon

# 2. One command: detect MCP servers & auto-configure agents
# (Also self-installs `/mcptoon` skill into all detected agents)
mcptoon quickstart

# 3. View compact tool catalog (-99.2% tokens)
mcptoon manifest

# 4. Route tasks to skills or doc chapters (<5ms)
mcptoon skills resolve "write git commit message"
mcptoon docs resolve "how does release gating work"

Is it actually saving you anything? After a fresh install mcptoon can sit in direct mode — installed but not wired into the agent — and save nothing. See Which mode is cheapest?, or just run mcptoon mode.

⚡ Core Capabilities at a Glance

💥 Save context (why ①)

🧩 One config, every agent (why ②)

• ✅ Compact name index (−99.2%): 255 tools → 581 tokens, full schema fetched on demand• ✅ Lossless result compression: reversible, retrieve the original behind any handle• ✅ Session dedup: byte-identical output in one turn becomes a reference• ✅ Skills the same way: one 39-token pointer + one lookup replaces every SKILL.md• ✅ Docs too: docs feeds 1 chapter, not 19 — 40k → 17k tokens per question• ✅ Honest numbers: real tiktoken accounting via mcptoon bench

• ✅ Native CLI: any shell-capable agent runs mcptoon and gets every feature — no MCP server, no config• ✅ GUI clients too: sync writes the JSON for Claude, Cursor, Cline, Windsurf, VS Code, Claude Code — 6 here, 103+ supported• ✅ Verified list: 42 clients run the CLI directly, 61 mount one mcptoon serve entry• ✅ Skills too: one catalog distributed to every agent's folder (skills sync)• ✅ Import what you have: pull servers from Claude / Cursor / Cline / Windsurf• ✅ One-command setup: quickstart = discover + configure + show tools• ✅ Fine control: toggle on/off, policy sets each tool's output tier, --version-gate / --tombstone for skills

🔍 Find & call (why ③)

🔌 Drive any API, not just MCP

• ✅ Cross-registry search: plain-language search across 17,000+ MCP servers• ✅ Discover what's already installed: discover scans existing client configs — nothing to reinstall• ✅ Call anything: call headless, or call --auto to auto-find the server• ✅ On-demand schema: inspect only when a tool is actually used• ✅ Pick for a task: select "<task>" returns just the top few• ✅ Export anywhere: manifest --format openai|openapi|mcp

• ✅ OpenAPI / Swagger: any REST API as commands (openapi list|call)• ✅ GraphQL: any endpoint as commands (graphql list|call)• ✅ OAuth built in: PKCE login, client-credentials, Dynamic Client Registration• ✅ MCP resources & prompts: resources, prompts, complete• ✅ Saved connections: bake — secrets by reference only (env: / file:)• ✅ Code sandbox: exec — only stdout enters context

🛡️ Safe, small, private	📚 Docs & doctor
• ✅ Zero dependencies: pure standard library, pyproject.toml clean• ✅ 565KB, installs in 2s• ✅ 100% local & private: no cloud, no telemetry, air-gap ready• ✅ Guards: destructive-op + prompt-injection + credential-leak checks on every call• ✅ XDG compliant: sandbox-friendly --dir isolation	• ✅ Docs router: docs indexes a Markdown tree, feeds 1 chapter instead of 19 (40k → 17k tokens)• ✅ Search inside docs: kb returns passages, not whole files (95KB → 3 snippets)• ✅ Self-heal: doctor repairs stdio pipes & environments; health probes every server• ✅ Live proof: bench / demo show the real numbers on your machine• ✅ Transparent footer: footer-facts prints live savings after each turn

Every command, with flags, is in All commands.

---

Why mcptoon: Solving Context Window Bloat & Multi-Agent Config Fragmentation

mcptoon is a zero-dependency local tool gateway and skill manager for LLM agents. In vanilla MCP architecture, every agent (Claude Code, Cursor, Windsurf, Codex, etc.) must inject the full JSON Schema definitions of all installed tools into its context window, resending them on every single turn.

According to our real-machine benchmark data: mounting just 255 common MCP tools consumes 71,929 tokens in descriptions alone, eating over half of a standard 128K context window before the first user prompt is processed. This not only inflates token costs unnecessarily, but also dilutes the model's attention, causing severe tool confusion and parameter hallucinations. mcptoon compresses these 71,929 tokens down to 581 tokens (−99.2%) using a compact name index, fetching schemas on demand only when a tool is actually called.

How Token Optimization Works: On-Demand Tool Retrieval & Dynamic Schemas

mcptoon keeps those descriptions on disk, not in context, and hands the agent a compact view instead:

• A name index, not full schemas. Picking a tool only needs its name — 255 tools become 581 tokens (−99.2%). The full schema is fetched on demand with mcptoon inspect, only when a tool is actually called.
• Skills the same way. One resident pointer (39 tokens) plus one lookup (791 tokens) replaces loading every SKILL.md in full — 1,572,330 → 39 + 791 (−99.99%).
• Results too. --toon re-encodes a tool's result as standard TOON. Measured 5.7% smaller on a mixed result sample, ranging 1.8%-48.6% by result shape — a list of records barely shrinks, a single record halves. Not a flat 34%: see assets/benchmark_results.json.

Nothing is lost: the full schema and the full skill text stay one command away. Only the context window is spared.

mcptoon is a 565KB, zero-dependency native CLI that manages every MCP tool and agent skill on your computer — and shares them across all your agents with no config written by you.

This isn't just us talking

Those numbers are ours — but "loading every tool schema into context is expensive" is not a claim only we make:

• Anthropic's engineering write-up — tool schemas flooding the context window is a real cost; one example drops from 150,000 tokens to 2,000
• Firecrawl's benchmark — the same task cost 1,365 tokens via CLI vs 44,026 via MCP (32×)
• Scalekit's benchmark — CLI 10–32× cheaper, 100% reliable vs MCP's 72%
• MCP-Zero (arXiv:2506.01056) — on-demand tool retrieval, near-constant cost regardless of tool count

mcptoon is the one you can use today: it covers any agent that can run a shell, and writes a single hookup line into the mainstream GUI clients it knows.

---

Two ways in

Install once, and every AI you have — Claude Desktop, Claude Code, Codex, Cursor, Windsurf, Cline, VS Code Copilot, Gemini CLI, Qwen Code, Zed, Crush, opencode and any other agent — shares all the tools and skills you already have. You write nothing in any agent's config.

→ Install and go

Script it. mcptoon is a plain CLI with stable JSON output and an mcptoon serve MCP endpoint — wire it into your own agent, CI, or app.

→ Commands and formats

Measure your numbers: pip install mcptoon && mcptoon bench — it reports your own catalog, not the fixed 255-tool sample below (that sample's method is in docs/tiktoken-benchmarks.md).

	Without mcptoon	With mcptoon
Descriptions in context	full description of every tool + skill, re-sent every turn	a compact view — 581 tokens for 255 tools (−99.2%, lossless)
Adding a tool or skill	hand-write JSON in every agent	one command — no agent config touched
Which agents get it	only the ones you configured	every agent on the machine — they just run mcptoon
Finding tools & skills	hunt GitHub by hand	install --search (17,000+ MCP servers) + skills search
Starting from scratch	wire tools one by one	4 built-in starter packs — one command to a working set

Skills work the same way: 1,572,330 tokens of SKILL.md text → 39 resident + 791 per lookup (−99.99%). Call results shrink a further ~6% with --toon (shape-dependent).

---

Path 1 · I just use AI tools

You have a desktop AI — Claude, Codex, Cursor, Windsurf, Cline, VS Code Copilot, and 97 more (full list of 103 →). Today, adding a tool or a skill means hand-editing that agent's JSON. mcptoon removes that step:

1. Install once.

   pip install mcptoon && mcptoon quickstart
   

   quickstart finds your MCP servers, writes your config, and registers mcptoon in every agent it detects. (Skip quickstart and the first command you run still self-heals: it installs mcptoon's own skill into each agent and builds the skill index, once per machine.)

2. Add tools and skills in one place — here, not in each agent.

   mcptoon install --search github     # find and install any MCP server
   mcptoon skills search "make a PDF"  # find a skill by what it does
   

3. Use them from any agent. Your agent runs mcptoon like any other command — no config, no restart. See Works with every AI agent.

Want a head start? Four built-in starter packs — essentials, web-research, code-review, docs — stand up a working toolset in one command:

mcptoon install --pack essentials

---

Path 2 · I build with MCP / agents

mcptoon is a plain CLI with scriptable output, plus an MCP endpoint when you want one.

mcptoon manifest --format json      # machine-readable tool index
mcptoon call <server> <tool> '{}'   # call any tool, JSON or --toon output
mcptoon serve                       # expose every configured server behind one MCP endpoint

• Stable output — JSON by default, --toon for smaller results (shape-dependent, 5.7% on a mixed sample), --format mcp to export standard MCP JSON.
• mcptoon serve — stdio or HTTP, connection pooling, per-agent keys, for clients that insist on a proxy.
• Zero dependencies — pure Python standard library, so it drops into any environment (CI, containers, air-gapped).

Full reference: DEVELOPERS.md and All commands.

---

Contents

• Why mcptoon
• How the token saving works
• This isn't just us talking
• Two ways in
• Path 1 · I just use AI tools
• Path 2 · I build with MCP / agents
• 30 seconds up and running
• What it does
• Where the tools come from
• The three bills
• Install
• Works with every AI agent — 103 clients (42 CLI · 61 serve)
• Why a CLI, not a proxy
• Which mode is cheapest?
• All commands
• Trust and safety
• Credits and references
• Contributing
• Troubleshooting & FAQ
• License

---

30 seconds up and running

pip install mcptoon                          # pure stdlib, 565KB, zero dependencies

# One command: find your MCP servers, write your config, register the gateway
# in every agent you have, and show you what it found:
mcptoon quickstart

# See every tool available (names-only by default; 255 tools cost 581 tokens):
mcptoon manifest

# Call a tool (JSON output by default; add --toon to save more).
# `everything` is only present if you already had it; otherwise add the built-in
# zero-dependency demo server first (no Node, no network) and call that:
mcptoon add demo --stdio python -m mcptoon demo-server
mcptoon call demo echo_message '{"message":"hi"}'

quickstart is also what makes mcptoon visible: it writes mcptoon serve into each agent's config as the reserved server mcptoon, so your agent can see mcptoon itself. Already synced? Re-register with mcptoon sync --self (plain mcptoon sync only writes your servers); check the state any time with mcptoon status.

Two ways in — and you don't pick one. mcptoon is a CLI first: a shell-capable agent runs mcptoon commands, and that is the cheapest path — the schemas never enter context. quickstart also registers mcptoon's own MCP entry (mcptoon serve) with each agent that takes one, so a client that can only see MCP servers still reaches your tools. The MCP entry ships in compact mode: it keeps your upstream tool list out of the model's context and sends it to mcptoon_manifest → inspect → call instead. mcptoon status shows both ledgers.

And it is fully reversible. The install registers the gateway, and by default quickstart also takes over — it routes your existing servers through the gateway and removes their direct entries (without that step your agent sees the same tools twice, once direct and once through the gateway, which costs more, not less). It is a listed, confirmed step, and it is undoable: mcptoon restore drops the gateway entry and puts your servers back exactly where they were. Anything you added to a config afterwards is left untouched. mcptoon off is the lighter switch — it removes only the gateway entry and leaves your servers where they are. Preview either with --dry, and preview the complete removal plan with mcptoon uninstall --dry (it prints exactly what it will remove first).

Don't want to install yet? Watch it work instead (needs Node):

uvx mcptoon demo --quick

It boots the official "everything" reference server, calls one tool, and prints the token math on your screen — no API key, none of your servers, nothing written to disk.

---

What it does

Tools: schema on demand

The full schema is compressed to a name index. When you need one, mcptoon inspect fetches its real parameters, then call runs it. You pay for a listing, not for every turn.

Skills: one resident pointer

No more loading the whole catalog. A single pointer line stays resident (39 tokens) and one lookup returns the most relevant skills (791 tokens). Views are links (a junction on Windows, no admin needed), so one edit at the source is live everywhere and there is no second copy to drift.