mcptoon

Add 1,000 MCP tools locally — your token context never feels it.

mcptoon is a 128KB CLI that keeps MCP tool schemas out of your agent's context. Tool discovery drops 71,929 → 581 tokens at 255 tools (−99.2%, measured); call results shrink another ~34% with --toon. One command per server, zero config, and every agent on your machine shares the same toolkit.

👉 中文 · Developer docs · Issues

pip install mcptoon

# Add any MCP server — one command:
mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch

# What your agent actually reads (names only — 581 tokens, not 71,929):
mcptoon manifest

Your tools stay yours. mcptoon bundles nothing — it's a remote control, not a runtime. The MCP servers you want, you install yourself, one command each (npm/pip/a URL). Delete mcptoon someday? Your MCP servers keep running on their own — not one goes missing.

Mcptoon is the native decoupling layer for MCP tools. It fixes the twin pain of MCP tool listings eating tokens and every AI agent re-configuring tools on its own. Zero config, out of the box: it auto-scans and unifies the MCP tools of every agent on this machine — Claude Code, Cursor, Codex, scripts, CI — shares tool instances globally, and slashes token overhead.

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: tool schemas flooding the context window is a real pain — one example drops from 150,000 tokens to 2,000 (a 98.7% saving)
• Firecrawl benchmark: the same task cost 1,365 tokens via CLI vs 44,026 via MCP — 32× (full schema loaded upfront)
• Scalekit benchmark: CLI is 10–32× cheaper and 100% reliable; MCP scores 72%
• MCP-Zero (arXiv:2506.01056): on-demand tool retrieval achieves near-constant cost regardless of tool count
• SEP-1576: an open MCP proposal to cut schema redundancy — the problem is acknowledged upstream

We're not the only ones who measured this. mcptoon is the one you can use today, covering every agent at once.

Up and running in 30 seconds

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

# Add any MCP server — one command:
mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch

# 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):
mcptoon call fetch fetch '{"url":"https://example.com"}'

Claude Code user? Skip the terminal entirely:

/plugin marketplace add activeing123/mcptoon

The plugin auto-installs the CLI (SessionStart hook), wires the mcptoon serve bridge via .mcp.json, and ships a skill that teaches the agent when to compress. /mcptoon-setup is the manual fallback.

Or let mcptoon auto-discover servers already on your machine:

mcptoon quickstart     # discover + configure + list tools — one command

That's it. No hand-written JSON config. No MCP protocol debugging. No polluted context window. The wheel is 128KB with zero dependencies, and mcptoon itself needs no API key and phones nothing home — $0 in service fees, everything runs on your machine.

The problem

Every MCP agent (Claude Code, Cursor, Codex, …) stuffs every tool's full schema into your context window before doing any work:

50 tools  → 14,113 tokens of schema → a 128K context: 11% gone
255 tools → 71,929 tokens of schema → a 128K context: 56% gone

So you unload servers you aren't using and reload them when you are. Back and forth. Adding one new server still means hand-writing a JSON config — one missing comma and everything breaks.

mcptoon fixes this. Your MCP servers stay configured, but their schemas never enter the agent's context by default. The agent just runs mcptoon commands, and only the compact result you asked for enters context — the name index weighs 581 tokens (114 for 50 tools, −99.2%).

Without mcptoon: 255 tools → 71,929 tokens, over half the window
With mcptoon:    255 tools → 581 tokens. 99.2% saved.

Both rows are measured configurations, not one number scaled up and down (tiktoken cl100k_base, assets/benchmark_tiktoken.json). Your mix will differ — compute your own numbers in the browser, 30 seconds, nothing uploaded.

The industry validated the problem — then gated the fix

Token-heavy tool context is no longer a niche complaint — it is now an official engineering problem, and the same answer keeps appearing on every roadmap:

• Anthropic: Tool Search Tool defers tool definitions until needed; Programmatic Tool Calling moves orchestration into code. Both are Claude-platform betas.
• MuleSoft: MCP Payload Optimization productizes clean → distill → compress (its compression stage is TOON). Enterprise gateway only, MCP up to 2025-06-18.

The direction is settled. mcptoon is the version of this answer you can run today, on every agent at once — the results-side discipline without the platform or gateway toll.

Installing MCP servers — one command each

# Install from npm (most MCP servers live here):
mcptoon install brave-search --npm @modelcontextprotocol/server-brave-search

# Install from pip:
mcptoon install my-tool --pip mcp-my-tool

# HTTP/SSE servers:
mcptoon install remote-api --url https://example.com/mcp

# List installed:
mcptoon install --list

# Uninstall:
mcptoon install --remove brave-search

mcptoon connects, discovers tools, generates the handler, registers it. No restart needed. Each install adds 0 KB to mcptoon itself — the CLI stays 128KB with zero dependencies, because servers are external processes your machine runs directly, not code bundled into mcptoon. Four steps, one command, no agent restart.

Any MCP server works:

mcptoon add my-server --stdio npx -y @any/mcp-package
mcptoon manifest    # usable immediately

Install as an agent skill (works with 80+ agents)

Teach your agent to use mcptoon through the open agent-skills ecosystem — the skill is picked up by Claude Code, Cursor, Codex, Cline, Windsurf and 75 more:

npx skills add https://github.com/activeing123/mcptoon --skill mcptoon

Prefer a GUI? ToonDeck

Don't want to hand-edit configs? ToonDeck is a local console for mcptoon: every MCP server and tool in one place with a real health check, one skill folder synced to all your agents, agent launching with live logs, and API keys stored in your OS keychain — never in a plaintext file.

pip install toondeck    # ships the web UI inside the wheel — no node, no build

Pre-alpha; free (Apache-2.0). ToonDeck drives the engine — mcptoon stays the single source of truth underneath.

Works with every AI agent

mcptoon is a CLI. If your agent can run a shell command, it can use mcptoon. No plugins, no SDK, no per-agent setup.

Configure once in ~/.mcptoon/config.json; every agent that can run shell commands shares the same servers and tools. GUI agents that can't? mcptoon sync writes native JSON into each one's own location.

export MCPTOON_AGENT_TYPE=claude   # call results a