Mcptoon

One Place for All Your Agents' MCP Tools and Skills.

Install 1,000 skills and 1,000 MCP tools locally — and never worry about context flooding.
Tools and skills configured in any single agent just work across Cursor, Claude Code, Codex, and 103+ desktop & terminal agents.
Pioneering on-demand schema retrieval out of the box — no more stuffing context windows, saving 99% context tokens.
Zero dependencies, pure local, offline-first.

_{If this saves you tokens, please star the repo — it helps other builders discover it.}

🌐 Official Website · 🧮 30s Token Tax Calculator · 🇨🇳 中文文档 · 📖 Developer Docs

_{Skeptical of a synthetic 255-tool sample? Here are 7 real public MCP servers (209 tools) measured on a real machine → — 640,606 → 905 tokens (−99.86%). Or run mcptoon bench on your own catalog.}

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

_{Also: OpenAPI / GraphQL passthrough · OAuth · MCP resources & prompts · saved connections · code sandbox — see All commands.}

pip install mcptoon && mcptoon quickstart — 565KB, zero dependencies, zero config.

_{Stays current on its own: it tells you when a newer version is out, and mcptoon upgrade updates in one command.}

🚀 Quick Start (Choose Your Way)

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

# 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

_{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

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).

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.

Install once, share everywhere

Install mcptoon once and every AI on the machine gets all your tools and skills. Add more later and it is live immediately — no agent restart, no per-agent JSON.

Add tools your way

mcptoon install brave-search --npm @modelcontextprotocol/server-brave-search
mcptoon install my-tool --pip mcp-my-tool
mcptoon install remote-api --url https://example.com/mcp
mcptoon add my-server --stdio npx -y @any/mcp-package
mcptoon install --list                       # see what's installed
mcptoon install --remove brave-search        # uninstall one

One command per server, from npm / pip / HTTP. Or let mcptoon scan what you already have: mcptoon discover.

A remote server that needs a token reads it from the environment, so no credential is ever written to disk:

mcptoon install remote-api --url https://example.com/mcp \
  --header 'Authorization: Bearer ${BAIZHI_TOKEN}'   # BAIZHI_TOKEN set in your environment

${NAME} is resolved at request time, so the config, the generated handler and every log keep the template — rotate the variable and the next call uses the new value, with no reinstall. A missing or empty variable fails loudly, naming it, never as an empty header.

Where tools come from — search across 17,000+ MCP servers with one command

On a new machine the first question isn't "how do I save tokens", it's "which tools do I even want". The old answer is to hunt GitHub for mcpServers snippets and hand-copy them into JSON.

mcptoon ships no tools and bundles no catalog. It queries the upstream registries, so you search for exactly what you need:

mcptoon install --search github     # search, list only — nothing installed
mcptoon install --search postgres
mcptoon install github              # search and install

Results carry a ✓ (registry-verified), a type tag (npm / pypi / hosted / remote) and a call count. Data comes from two upstreams, queried live and never stored:

Why nothing is bundled: a built-in list would need a release to update and would pull someone else's source into your supply chain. mcptoon stores only a pointer — the search writes one line into your own ~/.mcptoon/config.json; third-party source never lands inside mcptoon.

Then distribute to every agent:

mcptoon sync          # push the new tools to every detected agent
mcptoon manifest      # see every tool (name index, the cheapest view)

How to read a result: the index mixes official @modelcontextprotocol/* servers with packages individuals publish. A ✓ means the registry verified the entry — your cue to read the source before you hand it credentials.

The skills half: skills search <query> queries the open skills index (skills.sh) — find a skill by what it does, then install it with skills add <git-url>. mcptoon installs the repos you point it at — the catalog is the open ecosystem itself.

Starter packs: if you'd rather not pick tool-by-tool, four built-in packs — essentials, web-research, code-review, docs — each bundle a few tools plus a ready-made prompt. mcptoon install --packs lists them; mcptoon install --pack essentials installs one. The two research packs need no API key.

The three bills, and why you must not mix them

mcptoon saves tokens in three separate places. Comparing the numbers across them is meaningless.

The figures below come from catalogs of three different sizes — a 255-tool synthetic sample (the fixed headline benchmark), a 1,109-tool machine, and whatever your own machine has. Do not compare a percentage from one against a token count from another; each table states which catalog it measures.

There are two ways to read "how much does this save?", and they answer different questions. The gateway figure — full schemas versus what the agent actually loads under the default compact exposure — is what installing mcptoon buys, and it is the honest headline (it scales with catalog size: the more tools you have, the larger it gets). The slim-schema figure (same tools, terser descriptions) is the smaller, secondary claim (88.5%), and it is what manifest --slim buys. mcptoon status prints both, side by side, from one measurement, so the two can never drift apart.

Bill 1 · Tool discovery (manifest): 99.2% smaller by default

mcptoon manifest with no flags is this tier. Want more? --slim (names plus param types, 8,282 tokens, −88.5%) or --full (the complete schema).

Bill 2 · Call results (call): optional, --toon saves ~6%

This bill comes due after a tool returns. mcptoon call prints JSON by default and saves nothing by default. Add --toon to shrink the result.

Bill 3 · Skill catalog (skills): 1,572,330 → 39 resident + 791 per lookup

mcptoon skills manifest                      # 39 tokens, resident
mcptoon skills resolve "make a PDF" --k 5    # 791 tokens, the 5 most relevant

One table, all three, on the machine this README was written on:

The fixed headline benchmark — a synthetic sample of 255 tools across 50 servers, tiktoken cl100k_base. It is not your catalog; run mcptoon status to see your own numbers:

Measure your own catalog with mcptoon bench (it reports your tools, not this fixed sample). The exact three-format table above is reproducible too — no clone needed:

mcptoon manifest                 # populate the schema cache
python -m mcptoon.bench_tokens   # the same JSON / --slim / --compact counts, your tools

Method and caliber: docs/tiktoken-benchmarks.md.

Install

pip install mcptoon

Linux (Debian/Ubuntu 23.04+, and any distro that follows PEP 668), and Homebrew Python on macOS. A plain pip install into the system Python is refused there with error: externally-managed-environment. That is the distro protecting itself, not a problem with mcptoon. Install it the clean way instead:

pipx install mcptoon     # isolates the CLI; recommended
# or, into a virtualenv you control:
python3 -m venv ~/.mcptoon-venv && ~/.mcptoon-venv/bin/pip install mcptoon

pip install --break-system-packages mcptoon also works, but it writes into the system Python — prefer pipx or a venv. On Windows, pip install mcptoon just works.

# Run without installing (needs Node)
uvx mcptoon demo --quick

# Isolated CLI install (avoids the PEP 668 error on Linux / Homebrew Python)
pipx install mcptoon

# From source (for development)
git clone https://github.com/activeing123/mcptoon.git
cd mcptoon
pip install -e . --no-build-isolation

# Claude Code plugin
/plugin marketplace add activeing123/mcptoon

Nix

Packaged by numtide/llm-agents.nix — a bot follows every PyPI release, so the flake is never a version behind by hand:

# Run straight from the flake, no install step
nix run github:numtide/llm-agents.nix#mcptoon -- --help

The plugin and the skill are both surfaced through sudosubin/agents.nix as pkgs.agent-plugins.github.activeing123.mcptoon.<plugin-name> and pkgs.agent-skills.github.activeing123.mcptoon.<skill-name>.

Cross-Agent Support: Works with Cursor, Claude Code, Windsurf & 103+ Clients

mcptoon reaches an agent one of two ways, and every client below falls into one of them. You don't pick — quickstart registers both, and each host takes whichever it can:

• CLI leg — the agent runs mcptoon itself. Anything with a shell (a CLI agent, or a coding IDE with a terminal) needs zero config: it runs mcptoon call, mcptoon search, mcptoon skills resolve. Nothing is written into it at all.
• serve leg — the client can't run a shell. A chat app or GUI mounts MCP instead, so it gets one entry: mcptoon serve as a single MCP server. One line, one place.

The market, covered. 103 clients, taken from awesome-mcp-clients plus vendor docs for the coding agents that postdate it; developer libraries (mcp-agent, mcp-client-go) are excluded because a user does not run them. Evidence is per client — we name what we verified, not what we assumed.

CLI leg — 42 clients, zero config (they run mcptoon themselves):

AdaL · Aider · Amazon Q Developer · auggie · Autohand Code CLI · Claude Code · Claude Code Open · ClaudeMind · Cline · Codex · ContextKit · Continue · Copilot CLI · Copilot-MCP · Crush · Cursor · Dexto · Dolphin-MCP · Enola · Gemini CLI · Goose · JDBCX · Junie · KiloCode · Kiro · McPico · MCPOmni Connect · mistral-vibe · Nerve · Octomind · opencode · OpenHands · PraisonAI · Qwen Code · Roo Code · Slack MCP Client · SwarmClaw · Trae · VS Code GitHub Copilot · Warp · Windsurf · Zed

serve leg — 61 clients, one mcptoon serve entry (no shell, so they mount MCP):

5ire · Agent Bridge · Agent-cli · AgentOne · AIaW · Ano · AnythingLLM · Argo-LocalAI · askit-mcp · AstrBot · BoltAI · BrowseWiz · Canvas MCP Client · CarrotAI · Chainlit · ChatMCP · Cherry Studio · Claude Desktop · console-chat-gpt · DeepChat · DocsGPT · eechat · Enconvo · Fastchat MCP · FLUJO · Glue · HyperChat · kibitz · Klavis AI · LangBot · LibreChat · LobeHub · Lutra · MCP Chatbot · MCP CLI client · MCP Playground · MCP Simple Slackbot · MCP SuperAssistant · MCPCLIHost · MCPHost · Memex · MindPal · NextChat · OpenClaw · oterm · Qordinate · Runbear · SeekChat · Simple AI · Superinterface · Tambo · Taskade · Tester MCP Client · Tiles Notebook · Tome · Vercade · WhatsMCP · Witsy · y-cli · Yume · Zin-MCP-Client

Evidence status — sync --self writes a hookup line into the 12 hosts we have verified against their own docs; every other host above is reached by the CLI or by mcptoon serve

…