# 1 · install (or the one-liners below)
pip install mcptoon

# 2 · plug in — auto-discovers tools you already configured
mcptoon quickstart

# 3 · see it work on your own machine — no trust required
mcptoon demo

curl -fsSL https://raw.githubusercontent.com/activeing123/mcptoon/main/install.sh | bash

irm https://raw.githubusercontent.com/activeing123/mcptoon/main/install.ps1 | iex

pip install mcptoon        # pure stdlib, ~250KB, no deps

mcptoon quickstart         # finds servers you already configured, lists their tools
mcptoon demo               # live side-by-side: JSON vs mcptoon, real token counts

🗺️ Runtime architecture (interactive)

Below is the mcptoon runtime architecture diagram (generated from the real source; nodes carry SRC n links back to verified code evidence). Click the preview to open the interactive version: search nodes, trace call paths, compare semantic roles, toggle light/dark themes, and export.

⚡ Get it in 30 seconds (beginner entrance)

mcptoon is a cross-agent MCP management tool. Install it once, and every agent — Claude Code, Cursor, Codex — works with all your tools out of the box.

3 steps to install (no coding needed):

1. Install Python from python.org — check "Add Python to PATH"
2. Copy, paste, Enter: pip install mcptoon
3. One command: mcptoon quickstart, then mcptoon demo and watch it save tokens on your machine

Technical version in one sentence: mcptoon is a zero-dependency CLI that connects any agent to every Model Context Protocol server — whether or not the agent supports MCP.

🛠 Evaluate it in 30 seconds (technician entrance)

Architecture in one line: ~/.mcptoon/config.json is the single source of truth; sync writes it into every agent, manifest serves a name index on demand, serve composes a single-entry proxy. Zero third-party dependencies, Python 3.10+, ~6,800 lines of pure stdlib.

The part nobody else has: agents need zero setup

Native MCP means editing a JSON file for every agent, in every format:

Add a server in Cursor, forget Claude. Fix a path in Claude, break Cursor. Repeat weekly. Proxy tools mean running a service and pointing each agent at it.

mcptoon needs neither. It is a program your agent already knows how to run:

You:    "What tools do we have? Then fetch https://example.com and summarize."
Agent:  $ mcptoon manifest --compact        ← gets a name index, not schemas
Agent:  $ mcptoon call fetch fetch '{"url":"https://example.com"}'

No mcpServers entry. No plugin API. Nothing to register, nothing to restart. Want it automatic? One line in your agent's instruction file (CLAUDE.md / AGENTS.md / system prompt) is enough — that is prompting, not configuration.

This is also why mcptoon reaches where MCP cannot: shell scripts, CI pipelines, cron jobs, aider, terminal-only environments — anything that can execute a command.

The three moves

1 · Configure once — sync

mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch
mcptoon sync                # writes native config to every detected agent

Merges instead of overwriting — servers you configured manually stay put. One command gives you cross-agent tool management: a single source of truth for MCP servers across every agent on the machine, no copy-pasting JSON between Cursor, Claude and friends.

mcptoon sync --watch        # polls config files, keeps every agent aligned
mcptoon sync --dry          # preview the writes
mcptoon sync --agent cursor # target one agent

Drift detection catches external edits; merge/strict modes.

2 · Pay for names, not schemas — manifest

Your agent asks "what tools exist?" mcptoon answers with a name index. Schemas stay on disk in ~/.mcptoon/config.json and never enter the context.

$ mcptoon manifest --compact
fetch: fetch(url) · github: search_repos(q), get_file(repo, path) · sqlite: query(sql) · ...

_{Measured with tiktoken cl100k_base over a real-world 255-tool config (50 MCP servers). Your mix will differ. Reproduce: mcptoon manifest --compact --tokens. 71,929 tokens is roughly a 300-page book; 123 tokens is a sticky note.}

It is a dial, not a switch: --json is always available for zero ambiguity, and call results default to plain text, security-checked. Choosing between approaches? docs/comparison.md breaks down setup cost, token cost and safety.

3 · One door in front of every server — serve

Point your agent at a single entry instead of N servers:

"mcptoon": { "command": "mcptoon", "args": ["serve"] }

mcptoon serve                  # stdio — one agent
mcptoon serve --listen :8080   # HTTP — multiple agents, remote machines

Concurrency & stability

• Parallel discovery: 20 workers load the manifest; 100 servers in ≈5s (serial: 500s)
• 5-minute schema cache: repeated discovery costs nothing
• 30s timeout per call (MCPTOON_CALL_TIMEOUT): one hung server cannot stall your session
• Multiple agents at once: HTTP mode isolates concurrent requests per thread
• Concurrency-safe accounting: usage log uses thread locks + atomic writes

MCP spec compatibility (2026-07-28)

mcptoon 0.7.0 speaks the latest MCP specification, 2026-07-28 — the stateless revision — while staying fully compatible with every older server:

Version selection is automatic (spec="auto"): the client probes with server/discover and silently falls back to the legacy handshake when the server predates it. Pin a mode per server with spec: "legacy" or spec: "2026-07-28" in ~/.mcptoon/config.json.

mcptoon call db query '{"sql":"SELECT 1"}' --envelope   # complete MCP result envelope as JSON
mcptoon call deploy run '{}' --input-responses '{"env":"prod"}'   # MRTR retry (2026-07-28)

No flags needed for everyday use: when a new-spec server returns structured output, mcptoon picks it up automatically. --envelope is there when an agent needs the raw protocol payload (audit, debugging, _meta inspection).

Agent Plugins support (1.0.0)

The Agent Plugins Specification v1.0.0 (vendor-backed by Amazon, Cursor, Microsoft, OpenAI and Vercel) defines how an AI agent plugin is packaged — a folder with plugin.json + skills/ + mcp.json. It deliberately does not define installation, distribution or cross-agent sync. That is mcptoon's home turf:

mcptoon plugin scan <dir>        # validate a plugin package (read-only)
mcptoon plugin install <dir>     # install into mcptoon + every synced agent
mcptoon plugin list              # what is installed
mcptoon plugin remove <name>     # remove everywhere (data dir is kept)

• Strict spec validation — closed manifest schema, single-token commands, HTTPS-only non-loopback URLs, no credentials in headers, path-escape checks.
• ${PLUGIN_ROOT} / ${PLUGIN_DATA} pre-expanded — mcptoon is the installer, so it writes absolute paths into every agent's native config itself; agents need no plugin-loader support at all.
• Namespaced servers — plugin:server keys keep plugins collision-free, and removal cleans every agent config it reached.
• Persistent data — ~/.mcptoon/plugins-data/<name>/ survives upgrades (spec §PLUGIN_DATA), so caches and state never vanish on --force.
• Plugins land in the same ~/.mcptoon/config.json as every other server, so manifest, call, serve, health and the 99.8% token savings apply to them automatically.

Everything else in the box

Why health matters: a 2026 community audit found 52% of published MCP servers unreachable. Configured ≠ alive.

── mcptoon health: 3/5 alive ──────────────
  ✓ fetch     [stdio]  1 tool     120ms  ok
  ✗ brave     [stdio]  0 tools  10002ms  timeout → Timed out after 10s
  ✓ github    [http]  12 tools    340ms  ok

Under the hood

• Errors that agents can act on — every failure returns a structured envelope with a fix suggestion ("server fetchh not found — did you mean fetch?"), so your agent self-corrects instead of stalling until you rescue it
• Continuous sync (--watch) — drift detection with merge/strict modes
• Cross-server fuzzy search — relevance scoring across every configured server
• Shell completions — bash, zsh, fish and PowerShell
• JSON or TOML config — both live in ~/.mcptoon/
• Local usage log — which tools were called when; the record never leaves your machine

Security, applied to every call

Supply-chain safety comes free with zero dependencies: no npm subtree, no postinstall scripts, nothing to audit but ~6,800 lines of readable Python.

MCP servers run code on your machine and return arbitrary text into your agent's context. mcptoon inspects every result before it gets there:

No telemetry. No analytics. No phone-home. API keys pass through from your config or environment and are never stored by mcptoon.

Academic & Industry Validation

These independent sources validate the problem mcptoon solves:

Works with

Claude Desktop · Claude Code · Cursor · Cline · Windsurf · VS Code Copilot · Codex · Gemini CLI · OpenCode — plus aider, shell scripts, CI jobs and anything else that executes commands, including environments with no MCP support at all. That is what being a CLI first means.

❓ FAQ

👨‍💻 For developers

from mcptoon.client import MCPClient

with MCPClient(stdio=["npx", "-y", "@modelcontextprotocol/server-fetch"]) as c:
    tools = c.list_tools()
    result = c.call_tool("fetch", {"url": "https://example.com"})

git clone https://github.com/activeing123/mcptoon.git && cd mcptoon
pip install -e . --no-build-isolation && pip install pytest
python -m pytest tests/ -v          # 610 tests, green expected
docker run --rm -v ~/.mcptoon:/root/.mcptoon mcptoon manifest --compact

Zero third-party imports is a hard rule enforced in review. New features need tests. ~6,800 lines of Python across 14 modules — see CONTRIBUTING.md.

License

Apache 2.0 — see LICENSE and NOTICE.