Skip to content
Back to search

mcptoon

mcptoon plugin collection: MCP server manager and token-compression bridge for Claude Code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/activeing123/mcptoon with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/activeing123/mcptoon'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/activeing123--mcptoon/badge.svg)](/listings/activeing123--mcptoon)

HTML

<a href="/listings/activeing123--mcptoon"><img src="/api/listings/activeing123--mcptoon/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

<table> <tr> <td width="50%" valign="top">

<h4>🤖 Modern Way: Just Talk to Your Agent (Zero Memorization)</h4>

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!*

</td> <td width="50%" valign="top">

<h4>⚡ Terminal Way: 30-Second Setup</h4>

# 1. Install (zero dependencies, 363KB)
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"

</td> </tr> </table>

**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?](#which-mode-is-cheapest), or just run `mcptoon mode`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "mcptoon",
  3. "description": "mcptoon plugin collection: MCP server manager and token-compression bridge for Claude Code",
  4. "owner": {
  5. "name": "activeing123"
  6. },
  7. "strict": true,
  8. "plugins": [
  9. {
  10. "name": "mcptoon",
  11. "description": "MCP tool-catalog compression for Claude Code. Compresses the tool discovery payload from 71,929 to 581 tokens (-99.2%). Auto-installs the zero-dependency mcptoon CLI (/mcptoon-setup), wires the serve bridge, and teaches the agent when to compress. MCP 2026-07-28 stateless-first bridge included.",
  12. "author": {
  13. "name": "activeing123"
  14. },
  15. "source": "./claude-code-plugin",
  16. "homepage": "https://github.com/activeing123/mcptoon",
  17. "category": "mcp"
  18. }
  19. ]
  20. }
README.md · README · 952 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- mcp-name: io.github.activeing123/mcptoon -->
  2. <div align="center" markdown="1">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/activeing123/mcptoon/main/docs/assets/lockup-h-split-dark.svg">
  5. <img src="https://raw.githubusercontent.com/activeing123/mcptoon/main/docs/assets/lockup-h-split-light.svg" alt="mcptoon" height="88">
  6. </picture>
  7. <h3 align="center">One Place for All Your Agents' MCP Tools and Skills.</h3>
  8. <p align="center">
  9. <b>Install 1,000 skills and 1,000 MCP tools locally — and never worry about context flooding.</b><br>
  10. Tools and skills configured in any single agent just work across Cursor, Claude Code, Codex, and 103+ desktop & terminal agents.<br>
  11. Pioneering on-demand schema retrieval out of the box — no more stuffing context windows, <b>saving 99% context tokens</b>.<br>
  12. Zero dependencies, pure local, offline-first.
  13. </p>
  14. <p align="center">
  15. <sub>If this saves you tokens, please <a href="https://github.com/activeing123/mcptoon/stargazers">star the repo</a> — it helps other builders discover it.</sub>
  16. </p>
  17. <!-- Primary Status Badges -->
  18. <p align="center">
  19. <a href="https://pypi.org/project/mcptoon/"><img src="https://img.shields.io/pypi/v/mcptoon?style=flat-square&color=238636&logo=pypi&logoColor=white" alt="PyPI version"></a>
  20. <a href="https://github.com/activeing123/mcptoon/stargazers"><img src="https://img.shields.io/github/stars/activeing123/mcptoon?style=flat-square&logo=github&color=58a6ff" alt="GitHub Stars"></a>
  21. <a href="https://github.com/activeing123/mcptoon/actions"><img src="https://img.shields.io/github/actions/workflow/status/activeing123/mcptoon/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white" alt="CI Build"></a>
  22. <a href="#contributing"><img src="https://img.shields.io/badge/tests-3186%20passed-success?style=flat-square&logo=pytest&logoColor=white" alt="Tests"></a>
  23. <a href="https://github.com/activeing123/mcptoon"><img src="https://img.shields.io/badge/dependencies-0%20(stdlib%20only)-blue?style=flat-square" alt="Zero Dependencies"></a>
  24. <a href="https://github.com/activeing123/mcptoon/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-informational?style=flat-square" alt="License"></a>
  25. </p>
  26. <!-- Ecosystem & Directory Badges -->
  27. <p align="center">
  28. <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP_Spec-2026--07--28-blueviolet?style=flat-square" alt="MCP Spec"></a>
  29. <a href="https://allmcps.com/mcp/mcptoon?verify=7eb0d0d6-5d4e-41a3-a048-2fe3c91a36ed"><img src="https://img.shields.io/badge/AllMCPs-Listed-orange?style=flat-square" alt="AllMCPs"></a>
  30. <a href="https://mcpvault.io/servers/mcptoon/health"><img src="https://img.shields.io/badge/MCPVault-Verified-purple?style=flat-square" alt="MCPVault"></a>
  31. <a href="https://mcpservers.org/servers/activeing123/mcptoon"><img src="https://img.shields.io/badge/mcpservers.org-Listed-blue?style=flat-square" alt="mcpservers.org"></a>
  32. </p>
  33. <p align="center">
  34. <sub>Independently scored <b>4.2 / 5.0</b> by <a href="https://glama.ai/mcp/servers/activeing123/mcptoon">Glama</a> (TDQS, measured 2026-11-15).</sub>
  35. </p>
  36. <p align="center">
  37. <b><a href="https://mcptoon.github.io/">🌐 Official Website</a></b> ·
  38. <b><a href="https://mcptoon.github.io/tools/token-tax/">🧮 30s Token Tax Calculator</a></b> ·
  39. <b><a href="https://github.com/activeing123/mcptoon/blob/main/README.zh-CN.md">🇨🇳 中文文档</a></b> ·
  40. <b><a href="https://github.com/activeing123/mcptoon/blob/main/DEVELOPERS.md">📖 Developer Docs</a></b>
  41. </p>
  42. <!-- Modern Benchmark SVG -->
  43. <p align="center">
  44. <img src="https://raw.githubusercontent.com/activeing123/mcptoon/main/assets/benchmark.svg" alt="mcptoon Benchmark: 71,929 to 581 tokens (-99.2%)" width="100%" style="max-width: 960px; border-radius: 12px; margin: 16px 0;">
  45. </p>
  46. <p align="center">
  47. <sub>Skeptical of a synthetic 255-tool sample? <a href="https://github.com/activeing123/mcptoon/blob/main/docs/real-world-benchmark.md">Here are 7 real public MCP servers (209 tools) measured on a real machine →</a> — 640,606 → 905 tokens (−99.86%). Or run <code>mcptoon bench</code> on your own catalog.</sub>
  48. </p>
  49. <!-- Product promo video. Keep this as a BARE user-attachment URL on its own line:
  50. GitHub rewrites that form into a signed, playable player. Wrapping it in an
  51. explicit video HTML tag is NOT rewritten, and Chrome then rejects the raw
  52. github.com URL (it 302-redirects, failing the media URL safety check). -->
  53. https://github.com/user-attachments/assets/0272d3a8-c74f-428d-8559-fbf804ce0685
  54. <table>
  55. <tr>
  56. <td align="center" width="33%" valign="top">
  57. <br><b>① 💥 Tools, skills &amp; docs eating your context — afraid to add more?</b><br><br>
  58. Add as many as you like. Tool schemas <b>72k → 581 tokens</b>.<br>
  59. <sub>Tools −99.2% · Skills −99.99% · Docs 40k→17k per question</sub>
  60. </td>
  61. <td align="center" width="33%" valign="top">
  62. <br><b>② 🧩 Several agents — JSON configs and skills both a chore?</b><br><br>
  63. It's a <b>native CLI</b>: any agent that can run a shell command gets <b>every feature</b> — no MCP server, no config. <code>sync</code> covers the GUI clients too (<b>103+</b>).<br>
  64. <sub>No JSON editing, no restart</sub>
  65. </td>
  66. <td align="center" width="33%" valign="top">
  67. <br><b>③ 🔍 Overwhelmed by thousands of MCP tools across the web?</b><br><br>
  68. No more hunting for install docs. It first <b>scans and takes over the tools you already have</b>, then finds the rest by plain language — install and call on the spot.<br>
  69. <sub><code>mcptoon discover</code> (scan installed) → <code>search</code> (find online) → <code>call</code> (run directly)</sub>
  70. </td>
  71. </tr>
  72. </table>
  73. <p align="center">
  74. <sub>Also: OpenAPI / GraphQL passthrough · OAuth · MCP resources &amp; prompts · saved connections · code sandbox — <a href="#all-commands">see All commands</a>.</sub>
  75. </p>
  76. <p align="center">
  77. <b><code>pip install mcptoon &amp;&amp; mcptoon quickstart</code></b> — 565KB, zero dependencies, zero config.
  78. </p>
  79. <p align="center">
  80. <sub>Stays current on its own: it tells you when a newer version is out, and <code>mcptoon upgrade</code> updates in one command.</sub>
  81. </p>
  82. <!-- Common Problem Scenarios & SEO Use-Case Matrix -->
  83. <details>
  84. <summary><b>🔍 Common Pain Points & Solutions at a Glance (Click to expand)</b></summary>
  85. <br>
  86. <table>
  87. <tr><th>Your Pain Point / Search Intent</th><th>Vanilla MCP Behavior</th><th>mcptoon's Solution</th></tr>
  88. <tr><td><b>Context Window Bloat</b><br>Adding 10+ tools quickly hits context limits</td><td>Sends full JSON Schema of every tool every turn (70k+ tokens)</td><td><b>Compact Name Index</b>: ~2.2 tokens/tool on idle, schemas fetched on demand (99.2% token saving)</td></tr>
  89. <tr><td><b>Multi-Agent Sync Hell</b><br>Rewriting mcpServers JSON for Cursor, Claude Code, Windsurf</td><td>Manual copy-pasting into each client's config file</td><td><b>One-Command Takeover</b>: <code>mcptoon sync --takeover</code> automatically discovers and configures 103+ clients</td></tr>
  90. <tr><td><b>Headless CLI Execution</b><br>Need to call/test MCP tools directly in terminal/scripts</td><td>Requires spinning up full desktop agents or writing client code</td><td><b>Native Standard Library CLI</b>: <code>mcptoon call &lt;server&gt; &lt;tool&gt;</code> with zero dependencies</td></tr>
  91. <tr><td><b>Model Confusion & Hallucination</b><br>Too many candidate tools dilute model attention</td><td>Floods model with dozens of complex schemas simultaneously</td><td><b>Two-Stage Selection</b>: <code>mcptoon select "&lt;task&gt;"</code> pre-filters to the top 3 tools offline</td></tr>
  92. <tr><td><b>Agent Skills Fragmentation</b><br>Prompt instructions & skills can't be shared across agents</td><td>Manually duplicated across folders, drifting out of sync</td><td><b>Symlink-based Single-Source Hub</b>: <code>mcptoon skills sync</code>, 39-token pointer, zero duplication</td></tr>
  93. </table>
  94. </details>
  95. </div>
  96. ---
  97. ### 🚀 Quick Start (Choose Your Way)
  98. <table>
  99. <tr>
  100. <td width="50%" valign="top">
  101. <h4>🤖 Modern Way: Just Talk to Your Agent (Zero Memorization)</h4>
  102. 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**:
  103. ```markdown
  104. # Ask the built-in skill anytime:
  105. "Load /mcptoon skill and check what MCP tools I currently have."
  106. "Help me find an MCP tool that converts HTML to PDF and call it."
  107. "The tool output was truncated, retrieve the full original copy."
  108. "How many tokens did mcptoon save for me today?"
  109. "Doctor self-check: are all my MCP servers connected properly?"
  110. ```
  111. *Your agent loads `/mcptoon` and drives everything behind the scenes!*
  112. </td>
  113. <td width="50%" valign="top">
  114. <h4>⚡ Terminal Way: 30-Second Setup</h4>
  115. ```bash
  116. # 1. Install (zero dependencies, 565KB)
  117. pip install mcptoon
  118. # 2. One command: detect MCP servers & auto-configure agents
  119. # (Also self-installs `/mcptoon` skill into all detected agents)
  120. mcptoon quickstart
  121. # 3. View compact tool catalog (-99.2% tokens)
  122. mcptoon manifest
  123. # 4. Route tasks to skills or doc chapters (<5ms)
  124. mcptoon skills resolve "write git commit message"
  125. mcptoon docs resolve "how does release gating work"
  126. ```
  127. </td>
  128. </tr>
  129. </table>
  130. **Is it actually saving you anything?** After a fresh install mcptoon can sit in
  131. **direct** mode — installed but not wired into the agent — and save nothing. See
  132. [Which mode is cheapest?](#which-mode-is-cheapest), or just run `mcptoon mode`.
  133. ### ⚡ Core Capabilities at a Glance
  134. | 💥 Save context (why ①) | 🧩 One config, every agent (why ②) |
  135. | :--- | :--- |
  136. | • ✅ **Compact name index (−99.2%)**: 255 tools → **581 tokens**, full schema fetched on demand<br>• ✅ **Lossless result compression**: reversible, `retrieve` the original behind any handle<br>• ✅ **Session dedup**: byte-identical output in one turn becomes a reference<br>• ✅ **Skills the same way**: one 39-token pointer + one lookup replaces every `SKILL.md`<br>• ✅ **Docs too**: `docs` feeds 1 chapter, not 19 — **40k → 17k tokens per question**<br>• ✅ **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<br>• ✅ **GUI clients too**: `sync` writes the JSON for Claude, Cursor, Cline, Windsurf, VS Code, Claude Code — **6 here, 103+ supported**<br>• ✅ **Verified list**: 42 clients run the CLI directly, 61 mount one `mcptoon serve` entry<br>• ✅ **Skills too**: one catalog distributed to every agent's folder (`skills sync`)<br>• ✅ **Import what you have**: pull servers from Claude / Cursor / Cline / Windsurf<br>• ✅ **One-command setup**: `quickstart` = discover + configure + show tools<br>• ✅ **Fine control**: `toggle` on/off, `policy` sets each tool's output tier, `--version-gate` / `--tombstone` for skills |
  137. | 🔍 Find & call (why ③) | 🔌 Drive any API, not just MCP |
  138. | :--- | :--- |
  139. | • ✅ **Cross-registry search**: plain-language `search` across 17,000+ MCP servers<br>• ✅ **Discover what's already installed**: `discover` scans existing client configs — **nothing to reinstall**<br>• ✅ **Call anything**: `call` headless, or `call --auto` to auto-find the server<br>• ✅ **On-demand schema**: `inspect` only when a tool is actually used<br>• ✅ **Pick for a task**: `select "<task>"` returns just the top few<br>• ✅ **Export anywhere**: `manifest --format openai\|openapi\|mcp` | • ✅ **OpenAPI / Swagger**: any REST API as commands (`openapi list\|call`)<br>• ✅ **GraphQL**: any endpoint as commands (`graphql list\|call`)<br>• ✅ **OAuth built in**: PKCE login, client-credentials, Dynamic Client Registration<br>• ✅ **MCP resources & prompts**: `resources`, `prompts`, `complete`<br>• ✅ **Saved connections**: `bake` — secrets by reference only (`env:` / `file:`)<br>• ✅ **Code sandbox**: `exec` — only stdout enters context |
  140. | 🛡️ Safe, small, private | 📚 Docs & doctor |
  141. | :--- | :--- |
  142. | • ✅ **Zero dependencies**: pure standard library, `pyproject.toml` clean<br>• ✅ **565KB, installs in 2s**<br>• ✅ **100% local & private**: no cloud, no telemetry, air-gap ready<br>• ✅ **Guards**: destructive-op + prompt-injection + credential-leak checks on every call<br>• ✅ **XDG compliant**: sandbox-friendly `--dir` isolation | • ✅ **Docs router**: `docs` indexes a Markdown tree, feeds 1 chapter instead of 19 (40k → 17k tokens)<br>• ✅ **Search inside docs**: `kb` returns passages, not whole files (95KB → 3 snippets)<br>• ✅ **Self-heal**: `doctor` repairs stdio pipes & environments; `health` probes every server<br>• ✅ **Live proof**: `bench` / `demo` show the real numbers on your machine<br>• ✅ **Transparent footer**: `footer-facts` prints live savings after each turn |
  143. <sub>Every command, with flags, is in [All commands](#all-commands).</sub>
  144. ---
  145. ## Why mcptoon: Solving Context Window Bloat & Multi-Agent Config Fragmentation
  146. **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.
  147. 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.
  148. ## How Token Optimization Works: On-Demand Tool Retrieval & Dynamic Schemas
  149. mcptoon keeps those descriptions **on disk, not in context**, and hands the agent a compact view instead:
  150. - **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.
  151. - **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%)**.
  152. - **Results too.** `--toon` re-encodes a tool's *result* as standard TOON.
  153. Measured **5.7%** smaller on a mixed result sample, ranging **1.8%-48.6%** by
  154. result shape — a list of records barely shrinks, a single record halves. Not a
  155. flat 34%: see `assets/benchmark_results.json`.
  156. Nothing is lost: the full schema and the full skill text stay one command away. Only the context window is spared.
  157. 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.
  158. ## This isn't just us talking
  159. Those numbers are ours — but "loading every tool schema into context is expensive" is not
  160. a claim only we make:
  161. - **[Anthropic's engineering write-up](https://www.anthropic.com/engineering/code-execution-with-mcp)** — tool schemas flooding the context window is a real cost; one example drops from 150,000 tokens to 2,000
  162. - **[Firecrawl's benchmark](https://firecrawl.dev/blog/mcp-vs-cli)** — the same task cost 1,365 tokens via CLI vs 44,026 via MCP (32×)
  163. - **[Scalekit's benchmark](https://scalekit.com/blog/mcp-vs-cli-use)** — CLI 10–32× cheaper, 100% reliable vs MCP's 72%
  164. - **[MCP-Zero (arXiv:2506.01056)](https://arxiv.org/abs/2506.01056)** — on-demand tool retrieval, near-constant cost regardless of tool count
  165. 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.
  166. ---
  167. ## Two ways in
  168. <table>
  169. <tr>
  170. <td width="50%" valign="top">
  171. <h3>🧑‍💻 I just use AI tools</h3>
  172. 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.
  173. **[→ Install and go](#30-seconds-up-and-running)**
  174. </td>
  175. <td width="50%" valign="top">
  176. <h3>🔧 I build with MCP / agents</h3>
  177. 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.
  178. **[→ Commands and formats](#all-commands)**
  179. </td>
  180. </tr>
  181. </table>
  182. Measure *your* numbers: `pip install mcptoon && mcptoon bench` — it reports your own
  183. catalog, not the fixed 255-tool sample below (that sample's method is in
  184. [docs/tiktoken-benchmarks.md](https://github.com/activeing123/mcptoon/blob/main/docs/tiktoken-benchmarks.md)).
  185. | | Without mcptoon | With mcptoon |
  186. |---|---|---|
  187. | **Descriptions in context** | full description of every tool + skill, re-sent every turn | a compact view — **581 tokens** for 255 tools (−99.2%, lossless) |
  188. | **Adding a tool or skill** | hand-write JSON in every agent | one command — no agent config touched |
  189. | **Which agents get it** | only the ones you configured | every agent on the machine — they just run `mcptoon` |
  190. | **Finding tools & skills** | hunt GitHub by hand | `install --search` (**17,000+ MCP servers**) + `skills search` |
  191. | **Starting from scratch** | wire tools one by one | 4 built-in starter packs — one command to a working set |
  192. 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).
  193. ---
  194. ## Path 1 · I just use AI tools
  195. You have a desktop AI — Claude, Codex, Cursor, Windsurf, Cline, VS Code Copilot, and
  196. **97 more** ([full list of 103 →](#works-with-every-ai-agent)). Today, adding a tool or a
  197. skill means hand-editing that agent's JSON. mcptoon removes that step:
  198. 1. **Install once.**
  199. ```bash
  200. pip install mcptoon && mcptoon quickstart
  201. ```
  202. `quickstart` finds your MCP servers, writes your config, and registers mcptoon in every agent it detects.
  203. (Skip `quickstart` and the first command you run still self-heals: it installs
  204. mcptoon's own skill into each agent and builds the skill index, once per machine.)
  205. 2. **Add tools and skills in one place** — here, not in each agent.
  206. ```bash
  207. mcptoon install --search github # find and install any MCP server
  208. mcptoon skills search "make a PDF" # find a skill by what it does
  209. ```
  210. 3. **Use them from any agent.** Your agent runs `mcptoon` like any other command — no config, no restart. See [Works with every AI agent](#works-with-every-ai-agent).
  211. **Want a head start?** Four built-in starter packs — `essentials`, `web-research`, `code-review`, `docs` — stand up a working toolset in one command:
  212. ```bash
  213. mcptoon install --pack essentials
  214. ```
  215. ---
  216. ## Path 2 · I build with MCP / agents
  217. mcptoon is a plain CLI with scriptable output, plus an MCP endpoint when you want one.
  218. ```bash
  219. mcptoon manifest --format json # machine-readable tool index
  220. mcptoon call <server> <tool> '{}' # call any tool, JSON or --toon output
  221. mcptoon serve # expose every configured server behind one MCP endpoint
  222. ```
  223. - **Stable output** — JSON by default, `--toon` for smaller results (shape-dependent,
  224. 5.7% on a mixed sample), `--format mcp` to export standard MCP JSON.
  225. - **`mcptoon serve`** — stdio or HTTP, connection pooling, per-agent keys, for clients that insist on a proxy.
  226. - **Zero dependencies** — pure Python standard library, so it drops into any environment (CI, containers, air-gapped).
  227. Full reference: [DEVELOPERS.md](https://github.com/activeing123/mcptoon/blob/main/DEVELOPERS.md) and [All commands](#all-commands).
  228. ---
  229. ## Contents
  230. - [Why mcptoon](#why-mcptoon)
  231. - [How the token saving works](#how-the-token-saving-works)
  232. - [This isn't just us talking](#this-isnt-just-us-talking)
  233. - [Two ways in](#two-ways-in)
  234. - [Path 1 · I just use AI tools](#path-1--i-just-use-ai-tools)
  235. - [Path 2 · I build with MCP / agents](#path-2--i-build-with-mcp--agents)
  236. - [30 seconds up and running](#30-seconds-up-and-running)
  237. - [What it does](#what-it-does)
  238. - [Where the tools come from](#where-the-tools-come-from--search-17000-install-with-one-command)
  239. - [The three bills](#the-three-bills-and-why-you-must-not-mix-them)
  240. - [Install](#install)
  241. - [Works with every AI agent](#works-with-every-ai-agent) — **103 clients** (42 CLI · 61 serve)
  242. - [Why a CLI, not a proxy](#why-a-cli-not-a-proxy)
  243. - [Which mode is cheapest?](#which-mode-is-cheapest)
  244. - [All commands](#all-commands)
  245. - [Trust and safety](#trust-and-safety)
  246. - [Credits and references](#credits-and-references)
  247. - [Contributing](#contributing)
  248. - [Troubleshooting & FAQ](https://github.com/activeing123/mcptoon/blob/main/docs/faq.md)
  249. - [License](#license)
  250. ---
  251. ## 30 seconds up and running
  252. ```bash
  253. pip install mcptoon # pure stdlib, 565KB, zero dependencies
  254. # One command: find your MCP servers, write your config, register the gateway
  255. # in every agent you have, and show you what it found:
  256. mcptoon quickstart
  257. # See every tool available (names-only by default; 255 tools cost 581 tokens):
  258. mcptoon manifest
  259. # Call a tool (JSON output by default; add --toon to save more).
  260. # `everything` is only present if you already had it; otherwise add the built-in
  261. # zero-dependency demo server first (no Node, no network) and call that:
  262. mcptoon add demo --stdio python -m mcptoon demo-server
  263. mcptoon call demo echo_message '{"message":"hi"}'
  264. ```
  265. `quickstart` is also what makes mcptoon *visible*: it writes `mcptoon serve` into each
  266. agent's config as the reserved server `mcptoon`, so your agent can see mcptoon itself.
  267. Already synced? Re-register with `mcptoon sync --self` (plain `mcptoon sync` only writes
  268. your servers); check the state any time with `mcptoon status`.
  269. **Two ways in — and you don't pick one.** mcptoon is **a CLI first**: a shell-capable agent
  270. runs `mcptoon` commands, and that is the cheapest path — the schemas never enter context.
  271. `quickstart` also registers mcptoon's own MCP entry (`mcptoon serve`) with each agent that
  272. takes one, so a client that can only see MCP servers still reaches your tools. The MCP entry
  273. ships in `compact` mode: it keeps your upstream tool list out of the model's context and
  274. sends it to `mcptoon_manifest → inspect → call` instead. `mcptoon status` shows both ledgers.
  275. **And it is fully reversible.** The install registers the gateway, and by default
  276. quickstart also *takes over* — it routes your existing servers through the gateway
  277. and removes their direct entries (without that step your agent sees the same tools
  278. twice, once direct and once through the gateway, which costs *more*, not less). It
  279. is a listed, confirmed step, and it is undoable: **`mcptoon restore` drops the
  280. gateway entry and puts your servers back exactly where they were.** Anything you
  281. added to a config afterwards is left untouched. `mcptoon off` is the lighter
  282. switch — it removes only the gateway entry and leaves your servers where they are.
  283. Preview either with `--dry`, and preview the complete removal plan with
  284. `mcptoon uninstall --dry` (it prints exactly what it will remove first).
  285. Don't want to install yet? Watch it work instead (needs Node):
  286. ```bash
  287. uvx mcptoon demo --quick
  288. ```
  289. It boots the official "everything" reference server, calls one tool, and prints the token
  290. math on your screen — no API key, none of your servers, nothing written to disk.
  291. ---
  292. ## What it does
  293. ### Tools: schema on demand
  294. The full schema is compressed to a name index. When you need one, `mcptoon inspect`
  295. fetches its real parameters, then `call` runs it. You pay for a listing, not for every
  296. turn.
  297. ### Skills: one resident pointer
  298. No more loading the whole catalog. A single pointer line stays resident (39 tokens) and
  299. one lookup returns the most relevant skills (791 tokens). Views are **links** (a junction
  300. on Windows, no admin needed), so one edit at the source is live everywhere and there is no
  301. second copy to drift.
  302. ### Install once, share everywhere
  303. Install mcptoon once and every AI on the machine gets all your tools and skills. Add more
  304. later and it is live immediately — no agent restart, no per-agent JSON.
  305. ### Add tools your way
  306. ```bash
  307. mcptoon install brave-search --npm @modelcontextprotocol/server-brave-search
  308. mcptoon install my-tool --pip mcp-my-tool
  309. mcptoon install remote-api --url https://example.com/mcp
  310. mcptoon add my-server --stdio npx -y @any/mcp-package
  311. mcptoon install --list # see what's installed
  312. mcptoon install --remove brave-search # uninstall one
  313. ```
  314. One command per server, from npm / pip / HTTP. Or let mcptoon scan what you already have:
  315. `mcptoon discover`.
  316. A remote server that needs a token reads it from the environment, so no credential is
  317. ever written to disk:
  318. ```bash
  319. mcptoon install remote-api --url https://example.com/mcp \
  320. --header 'Authorization: Bearer ${BAIZHI_TOKEN}' # BAIZHI_TOKEN set in your environment
  321. ```
  322. `${NAME}` is resolved at request time, so the config, the generated handler and every log
  323. keep the template — rotate the variable and the next call uses the new value, with no
  324. reinstall. A missing or empty variable fails loudly, naming it, never as an empty header.
  325. ---
  326. ## Where tools come from — search across 17,000+ MCP servers with one command
  327. On a new machine the first question isn't "how do I save tokens", it's "which tools do I
  328. even want". The old answer is to hunt GitHub for `mcpServers` snippets and hand-copy them
  329. into JSON.
  330. mcptoon **ships no tools and bundles no catalog**. It queries the upstream registries, so
  331. you search for exactly what you need:
  332. ```bash
  333. mcptoon install --search github # search, list only — nothing installed
  334. mcptoon install --search postgres
  335. mcptoon install github # search and install
  336. ```
  337. Results carry a `✓` (registry-verified), a type tag (`npm` / `pypi` / `hosted` / `remote`)
  338. and a call count. Data comes from two upstreams, queried live and never stored:
  339. | Source | What it is | Scale |
  340. |---|---|---|
  341. | [Smithery](https://smithery.ai) | the largest MCP registry | **17,000+** entries |
  342. | [Official MCP Registry](https://registry.modelcontextprotocol.io) | the official meta-registry | installable npm / pypi packages |
  343. **Why nothing is bundled:** a built-in list would need a release to update and would pull
  344. someone else's source into your supply chain. mcptoon stores only a **pointer** — the
  345. search writes one line into your own `~/.mcptoon/config.json`; third-party source never
  346. lands inside mcptoon.
  347. Then distribute to every agent:
  348. ```bash
  349. mcptoon sync # push the new tools to every detected agent
  350. mcptoon manifest # see every tool (name index, the cheapest view)
  351. ```
  352. **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.
  353. **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.
  354. **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.
  355. ---
  356. ## The three bills, and why you must not mix them
  357. mcptoon saves tokens in three separate places. Comparing the numbers across them is
  358. meaningless.
  359. The figures below come from catalogs of three different sizes — a **255-tool synthetic
  360. sample** (the fixed headline benchmark), a **1,109-tool** machine, and whatever your own
  361. machine has. Do not compare a percentage from one against a token count from another;
  362. each table states which catalog it measures.
  363. There are two ways to read "how much does this save?", and they answer different
  364. questions. **The gateway figure** — full schemas versus what the agent actually loads
  365. under the default `compact` exposure — is what installing mcptoon buys, and it is the
  366. honest headline (it scales with catalog size: the more tools you have, the larger it
  367. gets). **The slim-schema figure** (same tools, terser descriptions) is the smaller,
  368. secondary claim (88.5%), and it is what `manifest --slim` buys. `mcptoon status` prints
  369. both, side by side, from one measurement, so the two can never drift apart.
  370. ### Bill 1 · Tool discovery (`manifest`): 99.2% smaller by default
  371. `mcptoon manifest` with no flags is this tier. Want more? `--slim` (names plus param
  372. types, 8,282 tokens, −88.5%) or `--full` (the complete schema).
  373. ### Bill 2 · Call results (`call`): optional, `--toon` saves ~6%
  374. This bill comes due *after* a tool returns. `mcptoon call` prints JSON by default and
  375. **saves nothing by default**. Add `--toon` to shrink the result.
  376. ### Bill 3 · Skill catalog (`skills`): 1,572,330 → 39 resident + 791 per lookup
  377. ```bash
  378. mcptoon skills manifest # 39 tokens, resident
  379. mcptoon skills resolve "make a PDF" --k 5 # 791 tokens, the 5 most relevant
  380. ```
  381. **One table, all three, on the machine this README was written on:**
  382. | Path | What the agent loads | Tokens | vs native |
  383. |---|---|---:|---:|
  384. | Tool schemas (212) | every full schema | 640,787 | — |
  385. | | `manifest` (name index) | 914 | 99.85% |
  386. | | `manifest --slim` | 3,056 | 99.52% |
  387. | Skill files (480) | every `SKILL.md`, full text | 1,572,330 | — |
  388. | | `skills manifest` (pointer) | 39 | 99.99% |
  389. | | `skills resolve --k 5` | 791 | 99.94% |
  390. The fixed headline benchmark — a **synthetic sample** of 255 tools across 50 servers,
  391. `tiktoken cl100k_base`. It is not your catalog; run `mcptoon status` to see your own
  392. numbers:
  393. | Format | Tokens | Savings |
  394. |---|---:|---:|
  395. | JSON | 71,929 | — |
  396. | TOON | 47,438 | 34% |
  397. | SLIM | 8,282 | 88.5% |
  398. | Compact | 581 | 99.2% |
  399. Measure your own catalog with `mcptoon bench` (it reports *your* tools, not this fixed
  400. sample). The exact three-format table above is reproducible too — no clone needed:
  401. ```bash
  402. mcptoon manifest # populate the schema cache
  403. python -m mcptoon.bench_tokens # the same JSON / --slim / --compact counts, your tools
  404. ```
  405. Method and caliber:
  406. [docs/tiktoken-benchmarks.md](https://github.com/activeing123/mcptoon/blob/main/docs/tiktoken-benchmarks.md).
  407. ---
  408. ## Install
  409. ```bash
  410. pip install mcptoon
  411. ```
  412. > **Linux (Debian/Ubuntu 23.04+, and any distro that follows PEP 668), and
  413. > Homebrew Python on macOS.** A plain `pip install` into the *system* Python is
  414. > refused there with `error: externally-managed-environment`. That is the distro
  415. > protecting itself, not a problem with mcptoon. Install it the clean way instead:
  416. >
  417. > ```bash
  418. > pipx install mcptoon # isolates the CLI; recommended
  419. > # or, into a virtualenv you control:
  420. > python3 -m venv ~/.mcptoon-venv && ~/.mcptoon-venv/bin/pip install mcptoon
  421. > ```
  422. >
  423. > `pip install --break-system-packages mcptoon` also works, but it writes into the
  424. > system Python — prefer `pipx` or a venv. On Windows, `pip install mcptoon` just works.
  425. <details>
  426. <summary>Other ways to install</summary>
  427. ```bash
  428. # Run without installing (needs Node)
  429. uvx mcptoon demo --quick
  430. # Isolated CLI install (avoids the PEP 668 error on Linux / Homebrew Python)
  431. pipx install mcptoon
  432. # From source (for development)
  433. git clone https://github.com/activeing123/mcptoon.git
  434. cd mcptoon
  435. pip install -e . --no-build-isolation
  436. # Claude Code plugin
  437. /plugin marketplace add activeing123/mcptoon
  438. ```
  439. </details>
  440. ### Nix
  441. Packaged by [numtide/llm-agents.nix](https://github.com/numtide/llm-agents.nix) — a bot follows
  442. every PyPI release, so the flake is never a version behind by hand:
  443. ```bash
  444. # Run straight from the flake, no install step
  445. nix run github:numtide/llm-agents.nix#mcptoon -- --help
  446. ```
  447. The plugin and the skill are both surfaced through
  448. [sudosubin/agents.nix](https://github.com/sudosubin/agents.nix) as
  449. `pkgs.agent-plugins.github.activeing123.mcptoon.<plugin-name>` and
  450. `pkgs.agent-skills.github.activeing123.mcptoon.<skill-name>`.
  451. ### Windows package managers
  452. ```powershell
  453. # Scoop - our own bucket; the manifest follows GitHub releases automatically
  454. scoop bucket add mcptoon https://github.com/activeing123/scoop-mcptoon
  455. scoop install mcptoon
  456. # Chocolatey - community repository, moderated
  457. choco install mcptoon
  458. ```
  459. > Chocolatey reviews every version before it goes live, so the version there can trail
  460. > the latest release by a few days. `choco upgrade mcptoon` picks up a new version once
  461. > it has been approved. The package embeds its own CPython, so no Python is required.
  462. >
  463. > winget: submitted as a pull request to `microsoft/winget-pkgs`, not merged yet —
  464. > `winget install mcptoon` does not work today, and this README will not claim otherwise
  465. > until it does.
  466. ---
  467. ## Cross-Agent Support: Works with Cursor, Claude Code, Windsurf & 103+ Clients
  468. mcptoon reaches an agent one of two ways, and every client below falls into one of them.
  469. You don't pick — `quickstart` registers both, and each host takes whichever it can:
  470. - **CLI leg — the agent runs `mcptoon` itself.** Anything with a shell (a CLI agent, or a
  471. coding IDE with a terminal) needs **zero config**: it runs `mcptoon call`, `mcptoon search`,
  472. `mcptoon skills resolve`. Nothing is written into it at all.
  473. - **serve leg — the client can't run a shell.** A chat app or GUI mounts MCP instead, so it
  474. gets **one entry**: `mcptoon serve` as a single MCP server. One line, one place.
  475. **The market, covered.** 103 clients, taken from
  476. [awesome-mcp-clients](https://github.com/punkpeye/awesome-mcp-clients) plus vendor docs for
  477. the coding agents that postdate it; developer *libraries* (mcp-agent, mcp-client-go) are
  478. excluded because a user does not run them. Evidence is per client — we name what we verified,
  479. not what we assumed.
  480. **CLI leg — 42 clients, zero config** (they run `mcptoon` themselves):
  481. AdaL · Aider · Amazon Q Developer · auggie · Autohand Code CLI · Claude Code · Claude Code Open ·
  482. ClaudeMind · Cline · Codex · ContextKit · Continue · Copilot CLI · Copilot-MCP · Crush · Cursor ·
  483. Dexto · Dolphin-MCP · Enola · Gemini CLI · Goose · JDBCX · Junie · KiloCode · Kiro · McPico ·
  484. MCPOmni Connect · mistral-vibe · Nerve · Octomind · opencode · OpenHands · PraisonAI · Qwen Code ·
  485. Roo Code · Slack MCP Client · SwarmClaw · Trae · VS Code GitHub Copilot · Warp · Windsurf · Zed
  486. **serve leg — 61 clients, one `mcptoon serve` entry** (no shell, so they mount MCP):
  487. 5ire · Agent Bridge · Agent-cli · AgentOne · AIaW · Ano · AnythingLLM · Argo-LocalAI · askit-mcp ·
  488. AstrBot · BoltAI · BrowseWiz · Canvas MCP Client · CarrotAI · Chainlit · ChatMCP · Cherry Studio ·
  489. Claude Desktop · console-chat-gpt · DeepChat · DocsGPT · eechat · Enconvo · Fastchat MCP · FLUJO ·
  490. Glue · HyperChat · kibitz · Klavis AI · LangBot · LibreChat · LobeHub · Lutra · MCP Chatbot ·
  491. MCP CLI client · MCP Playground · MCP Simple Slackbot · MCP SuperAssistant · MCPCLIHost · MCPHost ·
  492. Memex · MindPal · NextChat · OpenClaw · oterm · Qordinate · Runbear · SeekChat · Simple AI ·
  493. Superinterface · Tambo · Taskade · Tester MCP Client · Tiles Notebook · Tome · Vercade · WhatsMCP ·
  494. Witsy · y-cli · Yume · Zin-MCP-Client
  495. **Evidence status** — `sync --self` writes a hookup line into the 12 hosts we have verified
  496. against their own docs; every other host above is reached by the CLI or by `mcptoon serve`
  497. without a host-specific file, so there is nothing to verify per host.
  498. ### What mcptoon writes, host by host
  499. mcptoon is a **CLI tool** — a manager, not a resident proxy or service, and not a client
  500. library. Your agent never talks to your upstream MCP servers directly: it either runs
  501. `mcptoon` commands, or reaches them through mcptoon's own MCP entry (`mcptoon serve`).
  502. For the hosts that take a file, this is exactly what lands where:
  503. | Agent | How it hooks up |
  504. |---|---|
  505. | Claude Desktop | `mcptoon sync --self` adds one `mcptoon` entry to `claude_desktop_config.json` |
  506. | Claude Code | `mcptoon sync --self` writes its config and a pointer into `~/.claude/CLAUDE.md` |
  507. | Codex | `mcptoon sync --self` writes a pointer into `~/.codex/AGENTS.md` |
  508. | Gemini CLI | `mcptoon sync --self` writes a pointer into `~/.gemini/GEMINI.md` |
  509. | Qwen Code | `mcptoon sync --self` writes a pointer into `~/.qwen/QWEN.md` |
  510. | Zed | `mcptoon sync --self` writes a pointer into Zed's `AGENTS.md` |
  511. | Crush | `mcptoon sync --self` writes a pointer into `~/.config/crush/CRUSH.md` |
  512. | opencode | `mcptoon sync --self` writes a pointer into `~/.config/opencode/AGENTS.md` |
  513. | DSH | `mcptoon sync --self` writes a pointer into `$DSH_HOME/AGENTS.md` |
  514. | Cursor | `mcptoon sync --self` adds it to Cursor's MCP config; or put it in `AGENTS.md` |
  515. | Windsurf | `mcptoon sync --self` writes `mcp_config.json` |
  516. | Cline | `mcptoon sync --self` writes Cline's MCP config |
  517. | VS Code Copilot | `mcptoon sync --self` writes VS Code's MCP config |
  518. | Any agent that can run a shell | call `mcptoon` directly — zero config |
  519. ```bash
  520. # Agent needs GitHub access mid-task? It just runs:
  521. mcptoon add github --url https://api.githubcopilot.com/mcp/
  522. # Done. No JSON editing. No restart. No lost context.
  523. ```
  524. `mcptoon serve` is the other direction: run all your configured servers behind one MCP
  525. endpoint, with connection pooling and per-agent keys, for clients that insist on a proxy.
  526. You don't have to choose between the two — the CLI stays the primary way in, and the bridge
  527. is wired alongside it wherever the host can take one.
  528. ---
  529. ## Why a CLI, not a proxy
  530. MCP's premise is that every capability is a *server* your agent must be configured to
  531. reach — which is why one new tool means editing per-agent JSON in a different format for
  532. each, restarting everything, and re-paying the full schema cost in every agent.
  533. A command line is the one interface every agent already has. And the form factor is
  534. measurably cheaper on its own, before mcptoon does anything:
  535. - [Firecrawl](https://firecrawl.dev/blog/mcp-vs-cli): the same task cost **1,365 tokens via CLI vs 44,026 via MCP — 32×**
  536. - [Scalekit](https://scalekit.com/blog/mcp-vs-cli-use): CLI **10–32× cheaper, 100% reliable vs MCP's 72%**
  537. The proxy form exists too — `mcptoon serve` puts all configured servers behind one MCP
  538. endpoint — and `quickstart` wires it alongside the CLI, so you never have to choose. This
  539. section is about the shape mcptoon is built around, not a switch you have to flip.
  540. ---
  541. ## Which mode is cheapest?
  542. There are three ways mcptoon can hand tools to an agent, and they cost very
  543. differently. Only one is the cheapest, and it is not the state a fresh install
  544. starts in. (The token figures below are from the 255-tool sample; your own catalog
  545. differs — `mcptoon mode` prints your numbers.)
  546. | Mode | What the agent loads | Fixed cost every turn | When to use |
  547. |---|---|---|---|
  548. | **CLI** (cheapest) | nothing until it runs a command — then a name index (**581 tokens** for 255 tools) plus the one schema it needs | **0** | any agent that can run a shell |
  549. | **serve** | mcptoon's own gateway tools instead of every upstream schema (the gateway figure — scales with catalog size) | small, fixed | a client that can only see MCP servers |
  550. | **direct** | every full schema of every tool (**71,929 tokens** on the 255-tool sample) | **largest** | never, once mcptoon is installed |
  551. **CLI is cheapest because it is idle at zero.** It costs nothing on a turn that
  552. uses no tool, and a few hundred tokens only on the turn it does. `serve` is a close
  553. second — a small fixed bill every turn. `direct` is what you pay when mcptoon is
  554. installed but not wired into the agent, and it is where a fresh install sits, which
  555. is why mcptoon can feel invisible until you run `mcptoon quickstart`.
  556. The "99%" in this README is the **definition-side** saving — from not loading every
  557. schema. CLI and serve both get it; direct does not. Result compression is a separate,
  558. much smaller bill (Bill 2 above) and is never the reason to install.
  559. Find out which mode you are in — and what each costs on *your* catalog — with
  560. `mcptoon mode`; print a one-line badge with `mcptoon statusline`.
  561. ---
  562. ## All commands
  563. ```bash
  564. mcptoon quickstart # one-shot start (discover + configure + register the gateway)
  565. mcptoon discover # scan this machine for MCP servers (--write to keep, --health to probe)
  566. mcptoon import # import servers from Claude Desktop / Cursor / Cline / Windsurf
  567. mcptoon init # create a sample config (--auto to discover and fill it)
  568. mcptoon list # show configured servers
  569. mcptoon manifest # all tool names (compact by default; 255 tools = 581 tokens)
  570. mcptoon manifest --sort alpha|usage|recent # order the list (usage = your most-called first)
  571. mcptoon manifest --top 3 --verbose # cap to N tools per server; --verbose adds descriptions
  572. mcptoon inspect <server> <tool> # inspect one tool's schema
  573. mcptoon search <query> # search tools across servers
  574. mcptoon select "<task>" # top 3 tools for a task (past ~40 tools, models pick wrong)
  575. mcptoon select "<task>" --top 5 # ...or how many you want
  576. mcptoon call <server> <tool> '{"args":"here"}' # call a tool
  577. mcptoon call <server> <tool> ... --transport sse|streamable # HTTP transport preference (default auto)
  578. mcptoon exec python "print(len(open('big.log').readlines()))" # run code; only stdout enters context
  579. mcptoon exec python --file analyze.py # same, from a script file
  580. mcptoon exec --langs # what this machine can actually run
  581. mcptoon openapi list <spec> # any OpenAPI/Swagger REST API as commands
  582. mcptoon openapi call <spec> <cmd> pet-id=2 # call one operation (params: name=value)
  583. mcptoon openapi call <spec> <cmd> --base-url U # override the server (prod vs staging)
  584. mcptoon openapi call <spec> <cmd> --cache-ttl 0 --cache-key v2 # re-fetch the spec; keep versions apart
  585. mcptoon graphql list <endpoint> # any GraphQL endpoint as commands
  586. mcptoon graphql call <endpoint> <cmd> --fields "name id" # one query/mutation
  587. mcptoon auth login <name> --auth-url U --token-url U --client-id ID # OAuth (PKCE)
  588. mcptoon auth creds <name> --token-url U --client-id ID # OAuth client credentials
  589. mcptoon auth login <name> ... --register REG_URL --client-name mine # DCR (RFC 7591) — no client-id needed
  590. mcptoon openapi call <spec> <cmd> --auth oauth:<name> # use a stored token
  591. mcptoon resources list [server] # list a server's MCP resources
  592. mcptoon resources read <server> <uri> # read one resource by URI
  593. mcptoon prompts list [server] # list a server's prompt templates
  594. mcptoon prompts get <server> <name> a=1 # render a prompt with arguments
  595. mcptoon complete <server> <ref>:<arg>=<prefix> # ask the server to finish a value
  596. mcptoon bake create <name> --openapi <spec> # save a connection under a name
  597. mcptoon bake create <name> --openapi <spec> --auth-header 'K: env:VAR' # secret by reference only (env:/file:)
  598. mcptoon bake run <name> <action> ... # reuse a saved connection
  599. mcptoon bake install <name> --bin ~/.local/bin # write a launcher that only carries the bake name
  600. mcptoon add <name> --stdio|--http <cmd|url> # add any MCP server
  601. mcptoon remove <name> # remove a server
  602. mcptoon install <name> --npm|--pip|--url <pkg> # install + auto-generate handler
  603. mcptoon install --search <kw> # search the live registries (nothing installed)
  604. mcptoon update # refresh each server's cached tool surface; report what moved
  605. mcptoon upgrade # update mcptoon itself to the latest PyPI release
  606. mcptoon plugin install <dir> # install an Agent Plugins 1.0.0 plugin
  607. mcptoon sync # sync native config to every detected agent
  608. mcptoon health # health-check every MCP server
  609. mcptoon serve # run as an MCP server (stdio/HTTP)
  610. mcptoon skills list # list the skill catalog (--usage adds hit counts)
  611. mcptoon skills sync <src> # distribute a skill catalog to every agent's folder
  612. mcptoon skills resolve "<task>" # BM25 shortlist of skills (offline, no LLM)
  613. mcptoon docs index <dir> # index a Markdown tree so agents stop reading it whole
  614. mcptoon docs resolve "<query>" # best files for a query — returns paths (offline)
  615. mcptoon docs list # every indexed document, by slug
  616. mcptoon docs doctor # check the docs index against the disk
  617. mcptoon kb index <path> # index documents so you can search INSIDE them
  618. mcptoon kb fetch <url> # fetch a URL and index it (24h TTL cache)
  619. mcptoon kb search "<query>" # ranked passages, not whole files (porter + trigram, RRF)
  620. mcptoon kb list # indexed sources with size and age
  621. mcptoon kb stats # chunks, DB size, trigram support
  622. mcptoon session # what happened this session (catch up after a compaction)
  623. mcptoon bench # prove the savings on this machine (tools + skills, one table)
  624. mcptoon demo # one command, live demo on your machine
  625. mcptoon demo-server # the same proof with zero downloads (11 stdlib tools)
  626. mcptoon doctor # self-check: Python, config, connectivity
  627. mcptoon status # one screen: what's configured, gateway wired, tokens saved
  628. mcptoon stats # token-savings dashboard (vs raw JSON)
  629. mcptoon report # the whole savings account: tools + skills + cumulative
  630. mcptoon savings # milestones you've crossed (1B? ~12,000 novels?)
  631. mcptoon credit # one screen: your mode, what it really saves, one action
  632. mcptoon mode # which delivery mode you're in (cli/serve/direct) and what each costs
  633. mcptoon statusline # one-line savings badge for a status bar or turn header
  634. mcptoon usage # local call statistics
  635. mcptoon activity # who used mcptoon, when, on what (last 20 calls)
  636. mcptoon footer-facts # one line of savings for a chat footer (never blocks)
  637. mcptoon retrieve <handle> # get back the original behind any --smart handle
  638. mcptoon config # show gateway settings (footer, welcome, lang)
  639. mcptoon toggle <server> <tool> # enable/disable a single tool (--list to show all)
  640. mcptoon policy # per-tool compression policy (raw / toon / slim)
  641. mcptoon completion ps # shell completion (bash/zsh/fish/powershell)
  642. mcptoon off # remove the gateway entry from your agents (reversible)
  643. mcptoon restore # drop the gateway and put your servers back
  644. mcptoon uninstall # full cleanup — prints the plan first (--dry to preview)
  645. ```
  646. Full reference in [DEVELOPERS.md](https://github.com/activeing123/mcptoon/blob/main/DEVELOPERS.md).
  647. ### Format family: four tiers, compact by default
  648. All optional; the default is already the leanest tier.
  649. | Tier | Output | vs native schema | Origin |
  650. |---|---|---|---|
  651. | **compact (default)** | names only `search_web` | **99.2% smaller** | common design |
  652. | **slim** | name + param types `search_web\|query:s*` | 88.5% smaller | **mcptoon original** |
  653. | **full** | full schema with params | baseline | native MCP |
  654. | **toon** (results) | reversible structured encoding | 5.7% on a mixed sample (1.8-48.6% by shape) | open TOON standard |
  655. **Why compact by default?** Choosing *which* tool to use only needs names (581 tokens for
  656. 255 tools); parameter detail matters at call time and is fetched on demand. Defaulting to
  657. full schemas would hand the 99.2% right back.
  658. **The rule for agents: use `manifest` to choose, `inspect` before you call.** Measured on
  659. 41 live tools: an agent guessing arguments from names alone lands ~10% valid calls, while
  660. one that runs `inspect` once for the 2–3 tools a turn actually uses hits 100% — identical
  661. to injecting every schema, at a fraction of the cost.
  662. ---
  663. ## Trust and safety
  664. **It's just a 565KB native CLI — delete it anytime; keep it, and you never have to configure tools or skills for any agent again.** mcptoon touches your agent configs, so it is built to be transparent — and easy to walk away from.
  665. Three guards run on every tool result before your agent sees it:
  666. | Guard (on by default) | What it does |
  667. |---|---|
  668. | **Destructive-action block** | a dangerous call is refused unless you pass `--destructive` |
  669. | **Prompt-injection guard** | results are scanned for injection patterns like "ignore previous instructions" and blocked |
  670. | **Credential-leak detection** | a result carrying an API key or token is blocked before it enters context |
  671. - **Reversible.** `mcptoon restore` undoes a takeover (drops the gateway and returns
  672. your servers); `mcptoon off` removes only the gateway entry; `mcptoon uninstall
  673. --dry` prints the full removal plan first. Your servers are never deleted unless you ask.
  674. - **No telemetry.** No analytics, no crash reports, nothing phoned home.
  675. - **Local-first.** Your tools, skills and files stay on your machine. The only thing that leaves is `install --search`, which asks the registries for a catalog listing — it never sends your data.
  676. - **No stored credentials.** API keys pass straight from your config or environment.
  677. - **No dependencies.** Pure Python standard library — nothing in the supply chain to audit.
  678. CI enforces it with `scripts/check_zero_deps.py`.
  679. - **No daemon.** Pure CLI — no resident process, no listening port.
  680. - **Formats don't break compatibility.** The wire protocol is always standard JSON-RPC;
  681. compact/slim/toon only affect mcptoon's output to the agent. If `--toon` decoding ever
  682. fails it falls back to JSON, and one `--full` restores the native schema. No lock-in.
  683. **Scope, in one line:** mcptoon is an index and a config manager — it points you to each tool's own source, which you can review on its own terms.
  684. ---
  685. ## Credits and references
  686. - **[TOON standard](https://github.com/toon-format/toon)** — v4.1 (MIT), vendored from
  687. python-toon and credited in NOTICE
  688. - **[ToonDeck](https://github.com/activeing123/toondeck)** — a GUI console for mcptoon
  689. (pre-alpha): same engine, point and click instead of typing commands
  690. **Who builds this:** mcptoon is an independent third-party project maintained by
  691. [@activeing123](https://github.com/activeing123). It is not affiliated with Anthropic.
  692. ---
  693. ## Contributing
  694. ```bash
  695. git clone https://github.com/activeing123/mcptoon.git
  696. cd mcptoon
  697. pip install -e . --no-build-isolation
  698. pip install pytest pytest-cov
  699. python -m pytest tests/ -v # 3186 passed, 2 skipped
  700. ```
  701. Three hard rules: zero dependencies (CI-enforced), new behavior ships with tests, Windows
  702. is a first-class target. New here? Start with
  703. [CONTRIBUTING.md](https://github.com/activeing123/mcptoon/blob/main/CONTRIBUTING.md) and
  704. [DEVELOPERS.md](https://github.com/activeing123/mcptoon/blob/main/DEVELOPERS.md).
  705. The codebase: **41,845 lines of Python across 57 modules**, zero third-party dependencies.
  706. ---
  707. ## Support
  708. Hitting an error? [Troubleshooting & FAQ](https://github.com/activeing123/mcptoon/blob/main/docs/faq.md) covers the common ones
  709. (`Server 'X' not configured`, the `skills sync` mis-delete gate, unknown
  710. command/option exit codes, why a saving reads 99% not 100%, and a stale skills
  711. count).
  712. mcptoon is a one-person side project and stays free for individuals. If it cut your
  713. context bill:
  714. - **[Sponsor it on GitHub](https://github.com/sponsors/activeing123)** — one-off or monthly.
  715. - **[Star the repo](https://github.com/activeing123/mcptoon)** — that's how other builders find small tools.
  716. **Team features are not built yet.** One shared server list synced to every teammate's
  717. machine; a log of what got hydrated when. No pricing and no waitlist page — mail
  718. [activeing123@gmail.com](mailto:activeing123@gmail.com?subject=mcptoon%20team%20features)
  719. and it moves up the list.
  720. ---
  721. ## License
  722. Apache 2.0. See [LICENSE](https://github.com/activeing123/mcptoon/blob/main/LICENSE) and
  723. [NOTICE](https://github.com/activeing123/mcptoon/blob/main/NOTICE).
  724. ---
  725. <div align="center" markdown="1">
  726. *mcptoon is an independent third-party MCP client, not affiliated with Anthropic.*
  727. **If mcptoon cut your context bill, star it — that's how other builders find small tools.**
  728. [![Star History Chart](https://api.star-history.com/svg?repos=activeing123/mcptoon&type=Date)](https://star-history.com/#activeing123/mcptoon&Date)
  729. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.