{
"markdown": "\r\n\r\n\r\n# mcptoon\r\n\r\n**Add 1,000 MCP tools locally — your token context never feels it.**\r\n\r\nmcptoon is a CLI tool that sits between your AI agent and your MCP servers. Hook up as\r\nmany servers as you want — the agent's context window stays clean. Token savings happen\r\nin two separate places; don't mix them up:\r\n\r\n- **Tool discovery (saves by default, zero action)**: `mcptoon manifest` sends only the\r\n name list; schemas stay on disk — 255 tools drop from 71,929 to 581 tokens, −99.2%.\r\n- **Call results (optional)**: `mcptoon call` returns JSON by default; add `--toon` to\r\n shrink results by ~34% vs JSON (measured).\r\n\r\n**Mcptoon is the native decoupling layer for MCP tools.** It fixes the twin pain of\r\nMCP tool listings eating tokens and every AI agent re-configuring tools on its own.\r\nBuilt on agents' native CLI-calling ability: zero config, out of the box, it\r\nauto-scans and unifies the MCP tools of every agent on this machine, shares tool\r\ninstances globally, and slashes token overhead.\r\n\r\n**Your tools stay yours.** mcptoon bundles nothing — it's a 128KB CLI, like a remote\r\ncontrol. The MCP servers you want, you install yourself, one command each\r\n(npm/pip/a URL). Delete mcptoon someday? Your MCP servers keep running on their own —\r\nnot one goes missing.\r\n\r\nSavings start the moment you use it: 99.2% off tool discovery (measured), and every\r\nagent on this machine that can run a shell command — Claude Code, Cursor, Codex,\r\nscripts, CI — gets your full toolkit with no extra setup.\r\n\r\n[](https://pypi.org/project/mcptoon/)\r\n[](https://github.com/activeing123/mcptoon/actions/workflows/ci.yml)\r\n[](#contributing)\r\n[](https://modelcontextprotocol.io/specification/2026-07-28)\r\n[](https://github.com/activeing123/mcptoon/blob/main/LICENSE)\r\n\r\n**👉 `pip install mcptoon`** · [中文](https://github.com/activeing123/mcptoon/blob/main/README.zh-CN.md) · [Developer docs](https://github.com/activeing123/mcptoon/blob/main/DEVELOPERS.md) · [Issues](https://github.com/activeing123/mcptoon/issues)\r\n\r\n\r\n\r\n\r\n\r\n
\r\n\r\n---\r\n\r\n## This isn't just us talking\r\n\r\nThose numbers are ours, but \"loading every tool schema into context is expensive\" is\r\nnot a claim only we make:\r\n\r\n- [Anthropic](https://www.anthropic.com/engineering/code-execution-with-mcp): tool\r\n schemas flooding the context window is a real pain — one example drops from 150,000\r\n tokens to 2,000 (a 98.7% saving)\r\n- [Firecrawl benchmark](https://www.firecrawl.dev/blog/mcp-vs-cli): the same task cost\r\n 1,365 tokens via CLI vs 44,026 via MCP — 32× (full schema loaded upfront)\r\n- [Scalekit benchmark](https://www.scalekit.com/blog/mcp-vs-cli-use): CLI is 10–32×\r\n cheaper and 100% reliable; MCP scores 72%\r\n- [MCP-Zero (arXiv:2506.01056)](https://arxiv.org/abs/2506.01056): on-demand tool\r\n retrieval achieves near-constant cost regardless of tool count\r\n- [SEP-1576](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1576):\r\n an open MCP proposal to cut schema redundancy — the problem is acknowledged upstream\r\n\r\nWe're not the only ones who measured this. mcptoon is the one you can use today,\r\ncovering every agent at once.\r\n\r\n---\r\n\r\n## Up and running in 30 seconds\r\n\r\n```bash\r\npip install mcptoon # pure stdlib, 128KB, zero dependencies\r\n\r\n# Add any MCP server — one command:\r\nmcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch\r\n\r\n# See every tool available (names-only by default; 255 tools cost 581 tokens):\r\nmcptoon manifest\r\n\r\n# Call a tool (JSON output by default; add --toon to save more):\r\nmcptoon call fetch fetch '{\"url\":\"https://example.com\"}'\r\n```\r\n\r\n**Or let mcptoon auto-discover servers already on your machine:**\r\n\r\n```bash\r\nmcptoon quickstart # discover + configure + list tools — one command\r\n```\r\n\r\nThat's it. No hand-written JSON config. No MCP protocol debugging. No polluted context\r\nwindow.\r\n\r\n---\r\n\r\n## The problem\r\n\r\nEvery MCP agent (Claude Code, Cursor, Codex, …) stuffs **every tool's full schema into\r\nyour context window** before doing any work:\r\n\r\n```\r\n50 tools → 14,113 tokens of schema → a 128K context: 11% gone\r\n255 tools → 71,929 tokens of schema → a 128K context: 56% gone\r\n```\r\n\r\nSo you unload servers you aren't using and reload them when you are. Back and forth.\r\nAdding one new server still means hand-writing a JSON config — one missing comma and\r\neverything breaks.\r\n\r\n**mcptoon fixes this.** Your MCP servers stay configured, but their schemas **never\r\nenter the agent's context by default**. The agent just runs `mcptoon` commands, and\r\nonly the compact result you asked for enters context — the name index weighs 581\r\ntokens (114 for 50 tools, −99.2%).\r\n\r\n```\r\nWithout mcptoon: 255 tools → 71,929 tokens, over half the window\r\nWith mcptoon: 255 tools → 581 tokens. 99.2% saved.\r\n```\r\n\r\n*Both rows are measured configurations, not one number scaled up and down (tiktoken\r\n`cl100k_base`, `assets/benchmark_tiktoken.json`). Your mix will differ —\r\n[compute your own numbers in the browser](https://activeing123.github.io/mcptoon/tools/token-tax/),\r\n30 seconds, nothing uploaded.*\r\n\r\n---\r\n\r\n## Installing MCP servers — one command each\r\n\r\n```bash\r\n# Install from npm (most MCP servers live here):\r\nmcptoon install brave-search --npm @modelcontextprotocol/server-brave-search\r\n\r\n# Install from pip:\r\nmcptoon install my-tool --pip mcp-my-tool\r\n\r\n# HTTP/SSE servers:\r\nmcptoon install remote-api --url https://example.com/mcp\r\n\r\n# List installed:\r\nmcptoon install --list\r\n\r\n# Uninstall:\r\nmcptoon install --remove brave-search\r\n```\r\n\r\nmcptoon connects, discovers tools, generates the handler, registers it. No restart\r\nneeded.\r\n\r\n**Any MCP server works:**\r\n\r\n```bash\r\nmcptoon add my-server --stdio npx -y @any/mcp-package\r\nmcptoon manifest # usable immediately\r\n```\r\n\r\n---\r\n\r\n## Prefer a GUI? ToonDeck\r\n\r\nDon't want to hand-edit configs? **[ToonDeck](https://github.com/activeing123/toondeck)**\r\nis a local console for mcptoon: every MCP server and tool in one place with a\r\nreal health check, one skill folder synced to all your agents, agent launching\r\nwith live logs, and API keys stored in your OS keychain — never in a plaintext\r\nfile.\r\n\r\n```bash\r\npip install toondeck # ships the web UI inside the wheel — no node, no build\r\n```\r\n\r\nPre-alpha; free (Apache-2.0). ToonDeck drives the engine — mcptoon stays the\r\nsingle source of truth underneath.\r\n\r\n---\r\n\r\n## Works with every AI agent\r\n\r\nmcptoon is a CLI. **If your agent can run a shell command, it can use mcptoon.** No\r\nplugins, no SDK, no per-agent setup.\r\n\r\n| Agent | How |\r\n|---|---|\r\n| **Claude Code** | put `mcptoon` commands in SKILL.md |\r\n| **Codex (OpenAI)** | add `mcptoon` to AGENTS.md |\r\n| **Cursor** | add `mcptoon` to .cursorrules |\r\n| **OpenCode** | use `mcptoon` in custom commands |\r\n| **Any agent** | can run shell commands → can call `mcptoon` |\r\n\r\nConfigure once in `~/.mcptoon/config.json`; every agent that can run shell commands\r\nshares the same servers and tools. GUI agents that can't? `mcptoon sync` writes native\r\nJSON into each one's own location.\r\n\r\n```bash\r\nexport MCPTOON_AGENT_TYPE=claude # call results auto-select --toon\r\n# export MCPTOON_AGENT_TYPE=openai # or keep the default JSON\r\n```\r\n\r\nYour AI can even add tools by itself — no human in the loop:\r\n\r\n```bash\r\n# Agent needs GitHub access mid-task? It just runs:\r\nmcptoon add github --stdio npx -y @modelcontextprotocol/server-github\r\nmcptoon call github search_repos '{\"query\":\"mcp\"}'\r\n# Done. No JSON editing. No restart. No lost context.\r\n```\r\n\r\n---\r\n\r\n## The numbers\r\n\r\nmcptoon's token savings are two separate bills — know which one you're reading before\r\ncomparing numbers.\r\n\r\n### Bill 1 · Tool discovery (`manifest`): 99.2% saved by default\r\n\r\nThis bill comes due **before your agent decides \"which tool do I use\"**. Native MCP\r\nshoves every tool's full schema into context (50 tools: 14,113 tokens; 255 tools:\r\n71,929 tokens). mcptoon sends only the name index — that's where \"114, not 14,113\"\r\ncomes from.\r\n\r\n| Tools | Native schema (JSON) | mcptoon name index (default) | Saved |\r\n|-------|-------------------|------------------------|-------:|\r\n| 5 | 1,519 | 11 | −99.3% |\r\n| 50 | 14,113 | **114** | **−99.2%** |\r\n| 255 | 71,929 | **581** | **−99.2%** |\r\n\r\nZero action, on by default: `mcptoon manifest` with no flags is this tier.\r\nWant to give the agent more? `--full` (names + parameter types) saves 88.5%;\r\n`--json` (full schema) is the baseline.\r\n\r\n*Both rows are measured configurations, not one number scaled up and down (tiktoken\r\n`cl100k_base`, `assets/benchmark_tiktoken.json`). Your mix will differ —\r\n[compute your own numbers in the browser](https://activeing123.github.io/mcptoon/tools/token-tax/),\r\n30 seconds, nothing uploaded.*\r\n\r\n### Bill 2 · Call results (`call`): optional, --toon saves ~34%\r\n\r\nThis bill comes due **after a tool returns its result to your agent**. `mcptoon call`\r\noutputs JSON by default — yes, the default saves nothing. To shrink results too, add\r\n`--toon` (structured encoding, reversible):\r\n\r\n```\r\nDefault: mcptoon call fetch fetch '{\"url\":\"https://example.com\"}' → JSON (baseline)\r\nLeaner: mcptoon call fetch fetch '{\"url\":\"https://example.com\"}' --toon → ~34% saved\r\n```\r\n\r\n34% is the measured `toon_save` value in `assets/benchmark_tiktoken.json`\r\n(34.0–34.2%), not a marketing number.\r\n\r\n**One line to remember: 99.2% is what you save seeing which tools exist; 34% is what\r\nyou can further save on results.**\r\n\r\n### Side-by-side (Bill 1, made visible)\r\n\r\n**Without mcptoon** (what every MCP client stuffs into context — 37 tokens, measured\r\nwith tiktoken):\r\n\r\n```json\r\n[{\"name\":\"search_web\",\"description\":\"Search the web for information\",\r\n\"inputSchema\":{\"type\":\"object\",\"properties\":{\"query\":{\"type\":\"string\",\"description\":\"Search query\"}}}}]\r\n```\r\n\r\n**With mcptoon** (2 tokens):\r\n\r\n```\r\nsearch_web\r\n```\r\n\r\n**With mcptoon --full** (6 tokens, parameter info included):\r\n\r\n```\r\nsearch_web|query:s*\r\n```\r\n\r\n---\r\n\r\n## Security\r\n\r\nThree layers, all built in:\r\n\r\n| Layer | What it does | Example |\r\n|-------|-------------|---------|\r\n| **Destructive-action block** | dangerous actions blocked unless you pass `--destructive` | `db query '{\"sql\":\"DROP TABLE users\"}'` → blocked |\r\n| **Prompt-injection guard** | scans results for injection patterns | `\"ignore previous instructions\"` → blocked |\r\n| **Credential-leak detection** | scans results for exposed keys/tokens | `sk-abc...xyz` → blocked, never enters agent context |\r\n\r\n- **No telemetry.** No analytics, no crash reports, no call-home.\r\n- **No stored credentials.** API keys pass straight from your config or environment.\r\n- **No dependencies.** Pure Python standard library. Nothing in the supply chain to audit.\r\n- **No daemon.** Pure CLI — no resident process, no listening port, no attack surface.\r\n\r\n---\r\n\r\n## All commands\r\n\r\n```bash\r\nmcptoon quickstart # one-shot start (discover + configure + list tools)\r\nmcptoon list # show configured servers\r\nmcptoon manifest # all tool names (compact by default; 255 tools = 581 tokens)\r\nmcptoon manifest --full # tool schemas with params (88.5% smaller than native)\r\nmcptoon inspect # inspect one tool's schema\r\nmcptoon search # search tools across servers\r\nmcptoon call '{\"args\":\"here\"}' # call a tool\r\nmcptoon call --auto '{\"args\":\"here\"}' # auto-find the server\r\nmcptoon call --stdin # read large args from stdin\r\nmcptoon add --stdio|--http # add any MCP server\r\nmcptoon remove # remove a server\r\nmcptoon install --npm|--pip|--url # install + auto-generate handler\r\nmcptoon install --list # list installed\r\nmcptoon install --remove # uninstall\r\nmcptoon sync # sync native config to every detected agent\r\nmcptoon plugin install # install an Agent Plugins 1.0.0 plugin\r\nmcptoon serve # run as an MCP server (stdio/HTTP)\r\nmcptoon demo # one command, live demo on your machine\r\nmcptoon doctor # self-check: Python, config, connectivity\r\nmcptoon usage # local call statistics\r\nmcptoon completion ps # shell completion (bash/zsh/fish/powershell)\r\n```\r\n\r\n### Format family: four tiers, compact by default\r\n\r\nDiscovery and call results each have a set of formats — all optional, and the default\r\nis already the leanest tier:\r\n\r\n**manifest (discovery): compact by default, upgrade only if you want more**\r\n\r\n| Tier | Output | vs native schema | Origin |\r\n|---|---|---|---|\r\n| **compact (default)** | names only `search_web` | **99.2% smaller** | common design |\r\n| **slim** | name + param types `search_web\\|query:s*` | 88.5% smaller | **mcptoon original** |\r\n| **full** | full schema with params | baseline | native MCP |\r\n\r\n**Why compact by default, not full?** Deciding \"which tool do I use\" only needs names\r\n(581 tokens for 255 tools); parameter details matter at call time, fetched on demand\r\nvia `inspect` or `manifest --full`. Defaulting to full schemas hands the 99.2% right\r\nback.\r\n\r\n**call (results): JSON by default, --toon to save**\r\n\r\n| Tier | Output | vs JSON | Origin |\r\n|---|---|---|---|\r\n| **(default)** | JSON | baseline | common |\r\n| **--toon** | structured encoding (reversible) | ~34% smaller | open TOON standard |\r\n| **--mcptoon** | legacy pipe format | — | mcptoon original (legacy) |\r\n\r\n**Where these formats come from**\r\n\r\n- **compact**: a name list — any tool manager can do it; nothing proprietary.\r\n- **slim** (`name|param:type*` signatures): **an mcptoon original**, implemented in\r\n `output.py` (`slim_toon`, Apache 2.0); noted in NOTICE.\r\n- **full**: full JSON Schema — what MCP speaks natively.\r\n- **toon** (result encoding): integration of the open **TOON standard**\r\n ([toon-format/toon](https://github.com/toon-format/toon) v4.1, MIT), vendored from\r\n python-toon and credited in NOTICE — not our invention, and we don't claim it.\r\n\r\n---\r\n\r\n## Do custom formats break MCP compatibility? — No, for three reasons\r\n\r\n\"Proprietary format = compatibility bomb\" is a fair worry. It doesn't apply here:\r\n\r\n**1 · The protocol layer is always standard JSON-RPC; formats live only in the\r\npresentation layer.**\r\nmcptoon speaks standard MCP to servers (`initialize` / `tools/list` / `tools/call`).\r\ncompact/slim/toon only affect the \"mcptoon → agent\" output rendering — not a single\r\nbyte toward the server. Servers always see standard JSON; they don't even know these\r\nformats exist.\r\n\r\n**2 · --toon isn't proprietary; it's an open standard.**\r\nTOON (Token-Oriented Object Notation) is an external open standard\r\n([toon-format/toon](https://github.com/toon-format/toon) v4.1, MIT, official\r\nTypeScript reference implementation). We integrate python-toon (MIT);\r\n`tests/test_toon_cross_validate.py` verifies `decode(encode(x)) == x` case by case.\r\n\r\n**3 · There's a fallback; worst case you fall back to JSON.**\r\nIf `--toon` decoding fails it falls back to JSON automatically (`--fallback-json`);\r\nand call results are JSON by default anyway — `--toon` is optional. Want the full\r\nschema back? One `--full` is native MCP. No lock-in.\r\n\r\n**In one line: zero protocol changes, formats live in the output layer, worst case\r\nfalls back to JSON.** The feared \"server can't understand the custom format\" can't\r\nhappen — servers always hear standard JSON-RPC.\r\n\r\n---\r\n\r\n## How it works\r\n\r\nmcptoon is a **CLI tool**, not an MCP client library. Your agent doesn't connect to\r\nMCP servers — it runs `mcptoon` commands. Schemas live on disk in\r\n`~/.mcptoon/config.json`, out of the context window by default.\r\n\r\n**Two-layer decoupling:**\r\n\r\n```\r\nLayer 1: mcptoon CLI (128KB, zero deps)\r\n runs in the agent's shell. schemas stay out of context by default.\r\n │\r\nLayer 2: the actual MCP servers (npm/pip packages)\r\n start only when a tool is called. Zero cost when idle.\r\n```\r\n\r\n- 1,000 servers configured → 0 running, until you call one\r\n- mcptoon bundles nothing — you add what you want, one command each\r\n- Delete mcptoon? Your MCP servers keep running independently\r\n\r\n---\r\n\r\n## Why a CLI, not a proxy\r\n\r\nMCP's premise: every capability is a *server*, and your agent must be configured to\r\nreach it. That premise is why one new tool means editing per-agent JSON in a different\r\nformat for each, restarting everything — and why every agent re-pays the full schema\r\ncost before doing anything.\r\n\r\nA command line is the one interface every agent already has. And the form factor is\r\nmeasurably cheaper, independent of anything mcptoon does:\r\n\r\n- Firecrawl's benchmark: the same task cost **1,365 tokens via CLI vs 44,026 via MCP — 32×**\r\n- Scalekit's benchmark: CLI **10–32× cheaper, 100% reliable vs MCP's 72%**\r\n\r\nIf you truly need the proxy form, `mcptoon serve` is that mode — all configured\r\nservers behind one MCP endpoint, with connection pooling and per-agent API keys.\r\n\r\n---\r\n\r\n## Contributing\r\n\r\n```bash\r\ngit clone https://github.com/activeing123/mcptoon.git\r\ncd mcptoon\r\npip install -e . --no-build-isolation\r\npip install pytest pytest-cov\r\npython -m pytest tests/ -v # 738 passed, 1 skipped\r\n```\r\n\r\nZero dependencies is a hard rule. New features need tests. See\r\n[CONTRIBUTING.md](https://github.com/activeing123/mcptoon/blob/main/CONTRIBUTING.md) and [DEVELOPERS.md](https://github.com/activeing123/mcptoon/blob/main/DEVELOPERS.md).\r\n\r\nThe codebase: 11,400 lines of Python across 21 modules, zero third-party dependencies.\r\n\r\n---\r\n\r\n\r\n\r\n*mcptoon is an independent third-party MCP client, not affiliated with Anthropic.*\r\n\r\n**If this helps you, star it so more people can find it.**\r\n\r\n
\r\n",
"bytes": 18405,
"sha": "065455cfbb2e7bcbb49474395c3fa1c96814df90796ed0ae8751fac33b08e636",
"repo_slug": "activeing123/mcptoon",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_activeing123_mcptoon_bbdfe8e7/readme"
}