mcptoon

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

---

The problem

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

• Your agent connects to 5 MCP servers. Listing their tools: ~10,000 tokens of 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 tokens before any actual thinking happens.

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

The solution

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.

Show me

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.

Quick start

pip install mcptoon

Zero 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

How TOON works

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

Output formats

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.

vs. other MCP clients

	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

Works with every agent

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

Agent	How to use
Claude Code	Write mcptoon commands in SKILL.md files
Codex (OpenAI)	Add mcptoon to AGENTS.md
OpenCode	Use mcptoon in custom commands
Cursor	Add mcptoon to .cursorrules
CatPaw	Write mcptoon commands 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.

Claude Code

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"}'

Codex (OpenAI)

# 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 <server> <tool> '{"args":"here"}' --toon

Python API

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

Custom handlers — bypass MCP entirely

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

Config

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

Safety

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

Usage tracking

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

Architecture

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.

Privacy

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

License

Apache 2.0. See LICENSE and NOTICE.

Contributing

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.

---

mcptoon is an independent third-party MCP client. Not affiliated with Anthropic.

Found this useful? Star the repo to help others find it.

Report Bug | Request Feature