Connect agents to MCP servers with mcptoon

mcptoon keeps one config (~/.mcptoon/config.json) as the single source of truth for every MCP server an agent may use. It syncs that config into Claude Desktop, Claude Code, Cursor, Codex, Cline, Windsurf and VS Code, and can expose all servers through one stdio gateway (mcptoon serve).

First move: look before you change anything

mcptoon list            # what servers are configured right now
mcptoon doctor          # config syntax + connectivity diagnosis

If doctor reports problems, fix those before adding anything new.

Add servers

mcptoon discover                  # scan + probe locally installed MCP servers
mcptoon discover --write          # and write what was found into config
mcptoon add <name> --help         # see add options for stdio/http servers
mcptoon install <name> --npm @scope/pkg   # from npm
mcptoon install <name> --pip pkg          # from pip
mcptoon install <name> --url https://host/mcp   # streamable-http / sse

After editing ~/.mcptoon/config.json by hand, validate with mcptoon doctor.

Sync one config to every agent

mcptoon sync              # write config into all detected agents
mcptoon sync --dry        # preview only
mcptoon sync --agent claude   # one agent only

Expose everything through one gateway (recommended for agents)

Instead of registering N servers in an agent, register ONE:

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

mcptoon serve speaks MCP over stdio and forwards to every configured server. Benefits: one entry in the agent config, tool lists stay compact, and Plugin skills appear as MCP prompts automatically.

Token efficiency flags

Tool manifests can be huge. When calling mcptoon from a terminal, keep output small on purpose:

mcptoon manifest --toon        # standard TOON format (~34% saved)
mcptoon manifest --slim        # ultra-compact schemas (93% saved)
mcptoon manifest --compact     # names only (99.2% saved)
mcptoon search <query>         # find a tool without dumping the whole manifest
mcptoon inspect <server> <tool>   # full schema for exactly one tool

Toggles

Single tools can be disabled without removing the server (agents then never see them): toggle in ~/.mcptoon/config.json on the server entry, then mcptoon sync.

Rules of thumb

• Never edit agent-side config files directly; edit mcptoon's config and sync.
• mcptoon watch (if running) syncs on every save.
• Verify with mcptoon health — exit code 1 means something is down (CI-friendly).