MCP tool discovery costs 10,000+ tokens. mcptoon costs 350.

One MCP client for every AI agent. Cross-platform. Zero dependencies.

If this saves you tokens, please star the repo — it helps others discover it.

English | 中文文档 | Report Bug | Request Feature

Every MCP-enabled conversation burns tokens on syntax, not data:

• Your agent connects to 5 MCP servers. Listing their tools: ~10,000 tokensof JSON.
• Your agent calls 20 tools. Each returns 500-3,000 tokens wrapped in {"content":[{"type":"text","text":"..."}]}.
• Total MCP overhead: 40,000-70,000 tokensbefore any actual thinking happens.

On a 128K context window, that's 30-55% gone. Not on work. On syntax.

mcptoon is a CLI client that connects to any MCP server (stdio or HTTP) and outputs TOON (Token-Optimized Object Notation) instead of JSON.

| Operation | JSON tokens | mcptoon tokens | Savings |
|---|---|---|---|
| Tool discovery (96 tools) | ~2,000 | ~60 | 97% |
| Tool result (structured data) | ~800 | ~350 | 56% |
| Tool result (raw HTML/text) | ~1,000 | ~900 | 10% |

Zero dependencies. Pure Python. 50KB. Works with every AI agent — Claude Code, Codex, OpenCode, Cursor, CatPaw, anything that runs shell commands.

JSON (287 tokens) — what every other MCP client returns:

[ {"name": "search_web", "description": "Search the web for information", "inputSchema": {"type": "object", "properties": {"query": {"type": "string", "description": "Search query"}, "num_results": {"type": "number", "default": 5}}, "required": ["query"]}}, {"name": "fetch_url", "description": "Fetch content from a URL", "inputSchema": {"type": "object", "properties": {"url": {"type": "string"}}, "required": ["url"]}} ]
TOON (5 tokens) — what mcptoon returns:

search_web fetch_url
98% reduction for tool discovery, 60% for full schema, zero information lost.

pip install mcptoonZero dependencies. 50KB. Python 3.10+. Windows, macOS, Linux.

mcptoon init # Sample config: ~/.mcptoon/config.json mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch mcptoon manifest --toon # -> fetch:fetch mcptoon call fetch fetch '{"url":"https://example.com"}' --toon mcptoon call fetch fetch '{"url":"https://example.com"}' --json # when you need JSON
| JSON | TOON | Why |
|---|---|---|
| {"name":"search","count":3} | name:search|count:3 | Pipes replace braces + quotes + colon |
| [1, 2, 3] | 1 2 3 | Spaces replace brackets + commas |
| true/false | T/F | 1 char vs 4-5 |
| null | ∅ | 1 symbol vs 4 chars |
| "line1\nline2" | line1↲line2 | ↲ replaces escape sequence |
| {"a":{"b":[1,2]}} | a:b:1_2 | Recursive compaction |

| Flag | What you get | Token footprint |
|---|---|---|
| --toon | Compact notation, full semantics | 40-60% less than JSON |
| --compact | Tool names only, space-separated | 97% less than JSON |
| --json | Standard JSON (for scripts, CI) | Baseline |
| --raw | Raw response, no parsing | Full size |
| --head N | First N items only | Variable |
| --max-chars N | Hard truncate at N chars | Variable |
| --full | Disable the default 4000-char truncation | Full size |

Set MCPTOON_AGENT_TYPE=claude and every call auto-selects --toon.

| mcptoon | mcp-cli | mcporter | raw MCP SDK | |
|---|---|---|---|---|
| Token savings | 97% manifest, 40-60% results | 0% | 0% | 0% |
| Works with all agents | yes(Claude Code, Codex, OpenCode, Cursor, any) | Claude only | Claude only | varies |
| One config for all agents | yes | no | no | no |
| Output formats | TOON + JSON + compact | JSON | JSON | JSON |
| Dependencies | 0 | 5-20 | npm | 3-8 |
| Dangerous-op blocking | yes | no | no | no |
| Usage tracking | yes (local) | no | no | no |
| Schema cache | yes (5min) | no | no | no |
| Install size | ~50KB | ~50MB+ | ~30MB | ~10MB |
| Platform support | Windows, macOS, Linux | Linux/macOS | macOS | varies |

mcptoon is a CLI tool. If your agent can run shell commands, it can use mcptoon.

| Agent | How to use |
|---|---|
| Claude Code | Write mcptooncommands in SKILL.md files |
| Codex (OpenAI) | Add mcptoonto AGENTS.md |
| OpenCode | Use mcptoonin custom commands |
| Cursor | Add mcptoonto .cursorrules |
| CatPaw | Write mcptooncommands in skill files |
| Any agent | If it runs shell commands, it can call mcptoon |

Configure MCP servers once in ~/.mcptoon/config.json. Every agent shares the same servers, the same tools, the same token savings.

`export MCPTOON_AGENT_TYPE=claude # auto-select --toon````

In ~/.claude/skills/mcp-tools/SKILL.md

Search the web: mcptoon call exa search '{"query":"AI news"}'
List available tools: mcptoon manifest --toon
Fetch a URL: mcptoon call fetch fetch '{"url":"https://example.com"}'

In AGENTS.md or system prompt

Use mcptoon to call MCP tools. It saves 60% tokens vs JSON.
- List tools: mcptoon manifest --toon
- Call a tool: mcptoon call '{"args":"here"}' --toon

from mcptoon.client import MCPClient
from mcptoon.output import toon
with MCPClient(stdio=["npx", "-y", "@modelcontextprotocol/server-fetch"]) as c:
tools = c.list_tools()
print(toon(tools)) # compact TOON
result = c.call_tool("fetch", {"url": "https://example.com"})
print(toon(result))

from mcptoon.router import register
@register("my-database", "db")
def handle_db(tool, args):
if tool == "query":
return {"rows": my_db.execute(args["sql"])}
return None # falls through to MCP

stdio (any npx MCP server)

mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch
mcptoon add github --stdio npx -y @modelcontextprotocol/server-github

HTTP

mcptoon add myapi --http http://localhost:3001/mcp --header "Authorization: Bearer xxx"
`` Config lives at~/.mcptoon/config.json. Project-level override at./.mcptoon.json`.

mcptoon blocks operations that match dangerous patterns (delete, drop, purge, wipe, kill, etc.) unless you pass --destructive.

```
$ mcptoon call db delete_table '{"name":"users"}'
Error [CONFIRMATION_REQUIRED]: Dangerous operation needs confirmation
$ mcptoon call db delete_table '{"name":"users"}' --destructive

runs

$ mcptoon usage
Total calls: 142
Success rate: 138/142
Tokens (est): 84,200
By server:
fetch 89
github 53
`` Stored locally at~/.cache/mcptoon/usage.json`. Never transmitted.

src/mcptoon/ ├── cli.py # CLI entry + arg parsing ├── client.py # MCPClient — stdio + HTTP transport ├── router.py # Tool routing, custom handlers, safety checks ├── config.py # Server config ├── manifest.py # Tool discovery with cache ├── output.py # TOON / JSON / compact rendering ├── cache.py # Schema cache (5-min TTL) ├── usage.py # Local usage tracking └── errors.py # Structured error envelopes
~1,700 lines total. Zero third-party imports.

• No telemetry.No analytics, no crash reports, no phone-home.
• No credential storage.API keys pass through from your config or env vars.
• No dependencies.Pure Python stdlib. No supply chain to audit.

Found a vulnerability? Email security@activeing123.github.io. See SECURITY.md.

Apache 2.0. See LICENSE and NOTICE.

git clone https://github.com/activeing123/mcptoon.git cd mcptoon pip install -e . --no-build-isolation pip install pytest pytest-cov python -m pytest tests/ -v # 98 tests, 0.09s
Zero dependencies is a hard rule. New features need tests. See CONTRIBUTING.md.