mcptoon vs your current MCP manager

Bottom line: Your current MCP manager taxes your context window with schemas you might never use. mcptoon keeps tools outside the agent, calls them on demand, and compresses results. Your context window stays yours.

30-second quick start

pip install mcptoon                          # zero deps, ~250KB

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

# See all available tools (117 tokens for 255 tools):
mcptoon manifest --compact

# Call a tool — output is 30-93% smaller than JSON:
mcptoon call fetch fetch '{"url":"https://example.com"}' --toon

Or let mcptoon discover servers already on your machine:

mcptoon quickstart     # auto-discover + configure + show tools — all in one command

That's it. No JSON config editing. No MCP protocol debugging. No context window pollution.

Used by

Building something with mcptoon? Open an issue to be listed here.

What problem does this solve?

Every MCP-enabled agent (Claude Code, Cursor, Codex, etc.) loads all tool schemas into your context window before any work starts:

10 MCP servers → 50,000-100,000+ tokens of JSON schemas → 128K context: 40-80% gone
100 servers → 350,000+ tokens → context window is dead

So you unload servers when not needed. Reload when needed. Repeat. Forever. And adding a new server means hand-editing JSON config files — one syntax error and nothing works.

mcptoon fixes this. All your MCP servers stay configured, but their schemas never enter your agent's context. Your agent just runs mcptoon commands. Only the compact result you request enters context — and TOON encoding makes it 30-93% smaller than JSON.

Without mcptoon:  255 tools → 90,804 tokens of schemas in your context (tiktoken cl100k_base)
With mcptoon:      255 tools → 6,174 tokens (SLIM format). 93% savings.
                   255 tools → 117 tokens (compact, names only). 99.9% savings.

Install MCP servers — one command each

# From npm (most MCP servers live here):
mcptoon install brave-search --npm @anthropic/mcp-server-brave-search

# From pip:
mcptoon install my-tool --pip mcp-my-tool

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

# List what you have:
mcptoon install --list

# Remove:
mcptoon install --remove brave-search

mcptoon auto-connects, discovers tools, generates a handler, and registers it. No restart needed.

Works with any MCP server:

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

Works with shell-capable AI agents

mcptoon is a CLI tool, not an MCP Server. It does not plug into mcpServers JSON config. Instead, your agent calls mcptoon via shell commands — schemas stay out of context.

Works with (shell-capable agents):

Does NOT replace native MCP config:

• Cursor's mcpServers setting → unaffected (mcptoon is separate, not a server entry)
• Claude Desktop's claude_desktop_config.json → unaffected
• mcptoon does not output MCP JSON-RPC protocol stream — it is a client, not a server

Configure once in ~/.mcptoon/config.json. Every agent shares the same servers and tools. Switch agents — config follows you.

export MCPTOON_AGENT_TYPE=claude   # auto-select --toon for all calls

Your agent can even add tools on its own — no human intervention:

# Agent needs GitHub access mid-task? It runs:
mcptoon add github --stdio npx -y @modelcontextprotocol/server-github
mcptoon call github search_repos '{"query":"mcp"}' --toon
# Done. No JSON editing. No restart. No context lost.

The numbers

Token savings (255 tools, tiktoken cl100k_base)

All numbers from tiktoken.get_encoding("cl100k_base") — OpenAI's official BPE tokenizer.

• --compact → tool names only: 99.9% savings (tiktoken cl100k_base)
• --slim → tool schemas with params: 93% savings (tiktoken cl100k_base)
• --toon → structured results (round-trip safe): 30-40% savings

Reproduce: pip install tiktoken && python -c "import mcptoon; mcptoon._benchmark()" → outputs assets/benchmark_data.json

Before vs after — concrete example

Without mcptoon (what every MCP client puts in your context — 287 tokens):

[{"name":"search_web","description":"Search the web for information",
"inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"Search query"}}}}]

With mcptoon (5 tokens):

search_web

With mcptoon --slim (14 tokens, includes parameter info):

search_web|query:s*

Security

Three layers of protection, all built-in:

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

All commands

mcptoon quickstart              # one-command onboarding (discover + configure + show tools)
mcptoon init --auto             # auto-discover MCP servers on your machine
mcptoon add <name> --stdio npx -y <package>   # add any MCP server
mcptoon install <name> --npm <package>        # install + auto-generate handler
mcptoon list                    # show configured servers
mcptoon manifest --compact      # all tool names (117 tokens for 255 tools)
mcptoon manifest --slim         # tool schemas (93% smaller than JSON)
mcptoon manifest --toon         # standard TOON format
mcptoon inspect <server> <tool> # show one tool's schema
mcptoon search <query>          # search tools across all servers
mcptoon call <server> <tool> '{"args":"here"}' --toon   # call a tool
mcptoon call --auto <tool> '{"args":"here"}' --toon     # auto-find the server
mcptoon doctor                  # self-diagnose: Python, config, connectivity
mcptoon usage                   # local-only call statistics
mcptoon completion bash         # shell completion (bash/zsh/fish/ps)

Output formats

Note on --fallback-json: Only catches encoding-level errors (e.g., unsupported data types). It does not detect whether the LLM successfully parsed the output — that's the caller's responsibility.

How it works

mcptoon is a CLI tool, not an MCP client library or MCP Server. Your agent doesn't connect to MCP servers — it runs mcptoon commands. Schemas live on disk in ~/.mcptoon/config.json, not in your context window.

Architecture boundary:

• mcptoon is an MCP Client — it connects to MCP servers internally via stdio/HTTP
• mcptoon does not expose an MCP JSON-RPC endpoint for native MCP hosts
• --json output is a tool list fragment, not a full MCP protocol message (no initialize, id, method fields)
• To use with Cursor/Claude Desktop native MCP: configure their mcpServers separately. mcptoon is for shell-capable agents only.

Two layers, fully decoupled:

Layer 1: mcptoon CLI (~200KB, zero deps)
         Runs in your agent's shell. No schemas in context. Ever.
                    │
Layer 2: Actual MCP Servers (npm/pip packages)
         Launched on-demand only when you call a tool. Zero overhead until use.

• 1,000 servers configured → 0 running until you use one
• mcptoon ships zero bundled servers — you add what you want, one command each
• Delete mcptoon? Your MCP servers keep working independently

Python API

from mcptoon.client import MCPClient
from mcptoon.output import toon_encode, toon_decode

with MCPClient(stdio=["npx", "-y", "@modelcontextprotocol/server-fetch"]) as c:
    tools = c.list_tools()
    print(toon_encode(tools))         # compact TOON output
    result = c.call_tool("fetch", {"url": "https://example.com"})
    print(toon_encode(result))        # compact TOON output
    decoded = toon_decode(toon_encode(result))
    assert decoded == result          # round-trip safe

Architecture

src/mcptoon/
├── cli.py        # CLI entry + arg parsing
├── client.py     # MCPClient — stdio + HTTP transport
├── installer.py  # One-command MCP server installation + auto-handler
├── router.py     # Tool routing + poisoning/credential leak detection
├── config.py     # Server config (JSON + TOML)
├── manifest.py   # Tool discovery with cache + cross-server search
├── discover.py   # Zero-config auto-discovery (4-layer)
├── output.py     # TOON (vendored python-toon) + legacy mcptoon + compact/slim rendering
├── toon_vendored.py  # Vendored spec-compliant TOON encoder/decoder (MIT, python-toon v0.1.1)
├── cache.py      # Schema cache (5-min TTL)
├── usage.py      # Local usage tracking
└── errors.py     # Structured error envelopes + fix suggestions

~6,400 lines. 486 tests. Zero third-party imports. ~250KB source.

Docker

docker build -t mcptoon .
docker run --rm mcptoon help
docker run --rm -v ~/.mcptoon:/root/.mcptoon mcptoon manifest --toon

manifest, list, inspect, doctor work out of the box. call and add --stdio need the server runtime (e.g. npx) available in the image.

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   # 486 tests, 0.5s

Zero dependencies is a hard rule. New features need tests. See CONTRIBUTING.md.

License

Apache 2.0. See LICENSE and NOTICE.