The problem: MCP config hell

Every AI agent has its own MCP config format. Adding a tool means:

The reality: You have 3+ agents on your machine. Same MCP server, configured 3 times, in 3 different formats. Update one? Forget to update the others. Now they're out of sync.

"I just want to add a new MCP service. Why is it like going through hell?" — A real developer

The fix: one command, all agents

pip install mcptoon                          # zero deps, ~250KB

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

# Call from any agent — Claude Code, Cursor, Codex, anything:
mcptoon call fetch fetch '{"url":"https://example.com"}'

That's it. No .claude.json editing. No .mcp.json editing. No AGENTS.md editing.

Configure once in ~/.mcptoon/config.json. Every agent calls mcptoon via shell. Switch agents tomorrow — your tools are still there, zero reconfiguration.

MCP security firewall (built-in)

MCP servers can execute code on your machine. mcptoon is the firewall.

Current MCP security landscape:

• MCPoison (Check Point): Cursor RCE via MCP config tampering
• Tool Poisoning (Invariant Labs): Malicious instructions in tool responses — affects all major platforms
• 50 known CVEs in MCP ecosystem, 13 critical
• 200,000+ MCP servers exposed to RCE risk (OX Security)

mcptoon blocks these attacks with three layers — all built-in, zero config:

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

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:
mcptoon call fetch fetch '{"url":"https://example.com"}'

# Or let mcptoon discover servers already on your machine:
mcptoon quickstart     # auto-discover + configure + show tools — all in one command

Used by

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

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.

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

Token savings (bonus, not the point)

mcptoon keeps tool schemas outside your agent's context window. This is a side benefit of the CLI architecture — not the main selling point.

• --compact → tool names only: 99.9% savings (tiktoken cl100k_base)
• --slim → tool schemas with params: 93% savings
• --json → standard JSON (default)
• --toon → TOON encoding (optional, 30-40% 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.

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 inspect <server> <tool> # show one tool's schema
mcptoon search <query>          # search tools across all servers
mcptoon call <server> <tool> '{"args":"here"}'   # call a tool
mcptoon call --auto <tool> '{"args":"here"}'     # auto-find the server
mcptoon sync                   # sync config to all agents (Claude Desktop, Cursor, etc.)
mcptoon sync --dry             # preview what would be written
mcptoon sync --agent cursor    # sync to one agent only
mcptoon health                 # health check all servers (catches zombie servers)
mcptoon health --json           # JSON output for CI/CD (exit 1 if any dead)
mcptoon serve                  # run as stdio MCP server (1 Agent → 100 servers)
mcptoon doctor                  # self-diagnose: Python, config, connectivity
mcptoon usage                   # local-only call statistics
mcptoon completion bash         # shell completion (bash/zsh/fish/ps)

Sync config to all agents

Configure once in mcptoon, sync to every agent automatically:

mcptoon sync                 # writes to Claude Desktop, Cursor, Cline, Windsurf, VS Code Copilot
mcptoon sync --dry           # preview without writing
mcptoon sync --agent cursor  # sync to one agent only

mcptoon detects which agents you have installed and writes their native config format. No more editing .claude.json, .cursor/mcp.json, or settings.json by hand. Update in mcptoon → sync → all agents see the same servers.

Health check (catch zombie servers)

52% of MCP servers are unreachable (source). Check before you use:

mcptoon health                 # check all servers: alive, dead, latency, tool count
mcptoon health --timeout 5     # 5s timeout per server
mcptoon health --json           # JSON for CI/CD (exits 1 if any dead)

Output:

── mcptoon health: 3/5 alive, 2 dead ──

  ✓ fetch     [stdio]   3 tools    120ms  ok
  ✗ brave     [stdio]   0 tools  10002ms  timeout → Timed out after 10s
  ✓ github    [http]   12 tools    340ms  ok
  ✗ broken    [stdio]   0 tools    500ms  error → Connection refused

Perfect for CI/CD: mcptoon health --json || exit 1 in your pipeline.

Run as MCP server (serve mode)

mcptoon can also act as a single MCP server in front of your agent — proxying all underlying servers with safety checks:

// In your agent's mcpServers config:
"mcptoon": {
  "command": "mcptoon",
  "args": ["serve"]
}

• Agent connects to 1 server (mcptoon), not 100 individual servers
• All tool calls pass through mcptoon's security firewall (prompt injection + credential leak detection)
• Parallel manifest loading: 100 servers in ~5s
• Per-call timeout: no single server can hang the bridge
• Tool namespacing: {server}_{tool} prevents conflicts

mcptoon serve                  # stdio mode (for Claude Code, Cursor, etc.)
mcptoon serve --listen :8080   # HTTP mode (for remote/multi-agent)
mcptoon serve --auth <token>    # HTTP mode with Bearer token auth

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.

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()
    result = c.call_tool("fetch", {"url": "https://example.com"})

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) + compact/slim rendering
├── toon_vendored.py  # Vendored spec-compliant TOON encoder/decoder (MIT)
├── cache.py      # Schema cache (5-min TTL)
├── sync.py       # Config sync to AI agents (Claude Desktop, Cursor, Cline, etc.)
├── health.py     # Batch health check for all MCP servers
├── usage.py      # Local usage tracking
└── errors.py     # Structured error envelopes + fix suggestions

~6,800 lines. 513 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 --compact

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

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

License

Apache 2.0. See LICENSE and NOTICE.