The problem: MCP config hell
If you're using multiple AI coding agents, you've hit this wall.
You want to add the GitHub MCP server to your workflow. You use Claude Code, Cursor, and Codex. Here's what happens:
Claude Code wants ~/.claude.json:
{"mcpServers":{"github":{"command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"ghp_xxx"}}}}Cursor wants .cursor/mcp.json. Same JSON, different file, different location. Oh wait — is it .cursor/mcp.json or ~/.cursor/mcp.json? Depends on the version.
Codex wants AGENTS.md. That's Markdown. Different format entirely.
Same server. Three configs. Three formats. Three places to forget when your token expires.
And when you have 50+ tools across multiple servers, the token cost of loading all those JSON schemas into context is brutal — roughly 14,113 tokens just to discover what tools are available. At 255 tools, it balloons to 71,929 tokens — a 300-page book's worth of context eaten before any real work happens.
I lived through this. It sucked. So I built something to fix it.
The fix: mcptoon
pip install mcptoon # pure Python stdlib, ~250KB, zero dependencies
mcptoon add github --stdio npx -y @modelcontextprotocol/server-github
mcptoon sync # writes config to every detected agent
Done. Three commands. Every agent — Claude Code, Cursor, Codex, Cline, Windsurf, any shell-capable agent — can now call:
mcptoon call github search_repos '{"query":"mcp"}'
No JSON editing. No format differences. One config in ~/.mcptoon/config.json, shared across every agent.
The killer feature nobody else has: agents need zero setup on their side. mcptoon is a CLI — any agent that can run a shell command can use it, even agents that don't support MCP natively.
New in v0.5.5: continuous sync
But config drift is still a thing. You change a token, and later realize Cursor is still using the old one because you forgot to re-sync.
mcptoon sync --watch
Now mcptoon watches your config files using pure-stdlib polling (os.stat fingerprinting — no watchdog dependency, identical behavior on Windows, macOS and Linux). Change a token or add a server in ~/.mcptoon/config.json, and every agent's config updates automatically within seconds.
mcptoon sync --watch --interval 5 --quiet # daemon-friendly
Drift detection catches accidental external edits to agent configs too. Default mode re-merges (your manually-added servers stay safe). Or use --watch-mode strict to just get a warning.
How it works
mcptoon is a CLI tool, not an MCP server. It doesn't plug into mcpServers JSON. Instead, your agent runs mcptoon commands via shell.
Layer 1: mcptoon CLI (~250KB, zero deps)
Runs in your agent's shell. No JSON config in your agent.
│
Layer 2: MCP Servers (npm/pip packages)
Launched on-demand only when you call a tool.
Your agent calls mcptoon call fetch fetch '{"url":"https://example.com"}'. mcptoon connects to the MCP server, calls the tool, returns the result. The MCP server's schema never enters your agent's context window.
Token savings that actually matter
mcptoon doesn't just save you JSON editing. It changes what your agent loads into context.
| Tool listing (tiktoken cl100k_base) | Tokens | Savings |
|---|---|---|
| Raw JSON schemas, 255 tools | 71,929 | — |
--slim (names + params) |
8,282 | −88.5% |
--compact (names only) |
123 | −99.8% |
In human terms: 71,929 tokens is a 300-page book. 123 tokens is a sticky note.
This is a dial, not a switch — --json is always available when you need full schemas. And mcptoon call results can be encoded as TOON format, saving another ~34% on result payloads.
Full category-level numbers across approaches in docs/comparison.md.
Why zero dependencies matters
mcptoon is pure Python stdlib. No requirements.txt. No supply chain to audit.
~6,800 lines. 531 tests. Zero third-party imports. ~250KB source.
Every dependency is a potential attack vector. Zero dependencies means mcptoon itself has a minimal attack surface. We also verified this with an AST-based zero-dep gate in CI that catches any accidental third-party import, including patterns where try/except ImportError wraps optional enhancements.
Built-in security firewall
MCP servers can execute code on your machine. That's the point — but a malicious server can do real damage.
mcptoon inspects every tool result before it reaches your agent:
| Layer | What it does |
|---|---|
| Prompt injection guard | Blocks hidden instructions like "ignore previous instructions" |
| Credential leak guard | Scans for exposed API keys (AWS, GitHub, OpenAI, Slack, etc.) |
| Dangerous-op blocker | Blocks delete/drop/purge operations by default |
Most agents load tool responses directly into context without any inspection. That's how Tool Poisoning works — a malicious server returns hidden instructions, and the LLM executes them. mcptoon stops that at the gate.
Cross-agent tool management
When you have multiple agents sharing the same tools, you need a single source of truth for MCP config. mcptoon provides:
-
sync— one config, written to every detected agent's native format -
health— check all servers across agents with timeouts; exit code for CI -
manifest— see what tools each agent has access to -
--watch— keep everything aligned continuously
It's the cross-agent tool management CLI: one command per operation, every agent covered.
Getting started
pip install mcptoon
mcptoon quickstart # auto-detect existing configs
mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch
mcptoon sync --watch # keep every agent aligned
mcptoon manifest --compact --tokens # see: 123 tokens vs 71,929 raw
GitHub: https://github.com/activeing123/mcptoon
PyPI: https://pypi.org/project/mcptoon/
License: Apache 2.0
mcptoon is an independent third-party MCP client. Not affiliated with Anthropic, OpenAI, or Cursor.