RELATED 01
1MCP
Runs many MCP servers behind one local runtime and hands each client a filtered view of them
529GitHub stars
1.7k/wknpm downloads
64popularity score
mcptoon
Gateway that puts all your MCP servers behind one entry and keeps their tool schemas out of context
By Alex Chen (individual) Python Local · stdio Developer tools
66 popularity score ★ 422 ↓ 4.8k/mo
Connect your client
Local (PyPI)
Add in one click
Opens the app, which asks before it adds the server.
Or add it by command or config
FirstTerminal
pipx install mcptoonClaude CodeTerminal
claude mcp add mcptoon -- mcptoon serveClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"mcptoon": {
"command": "mcptoon",
"args": [
"serve"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"mcptoon": {
"command": "mcptoon",
"args": [
"serve"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"mcptoon": {
"type": "stdio",
"command": "mcptoon",
"args": [
"serve"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.mcptoon]
command = "mcptoon"
args = ["serve"]Gemini CLITerminal
gemini mcp add --scope user mcptoon mcptoon -- serveSettings 4
MCPTOON_CALL_TIMEOUT |
Optional: Seconds before one upstream tool call is stopped; 30 by default. |
|---|---|
MCPTOON_CACHE_TTL |
Optional: How long upstream tool schemas stay cached; 5 minutes by default. |
MCPTOON_AUTH_TOKEN |
Optional: Bearer token for HTTP mode (same as --auth); needed to listen on a non-loopback address. |
MCPTOON_ALLOWED_HOSTS |
Optional: Comma-separated extra hostnames accepted in HTTP mode's Origin and Host checks. |
What it does
mcptoon is a Python command-line tool that manages the MCP servers and agent skills on one machine. Its MCP side is `mcptoon serve`: a single gateway entry that starts every server you have configured in mcptoon and passes calls through to them, so each agent needs one config line instead of one per server.
The point is token cost. By default the gateway runs in `compact` exposure: the client's tool list holds only mcptoon's own nine tools, not the upstream ones. The model asks `mcptoon_manifest` for tool names, `mcptoon_inspect` for one tool's parameters, then runs it with `mcptoon_call`. The `full` exposure setting lists every upstream tool too, with a simplified schema, as namespaced `server_tool` names (src/mcptoon/serve.py at v0.8.20). Long results can be compressed and fetched back whole with `mcptoon_retrieve`, and a local skill catalog can be searched with `mcptoon_resolve_skills`.
The package has no third-party dependencies. The same CLI also searches public MCP registries, installs servers into its config, writes its own entry into the configs of the agents it detects (`mcptoon quickstart`, undone with `mcptoon restore`), and reports token counts with `mcptoon bench`.
At v0.8.20 the gateway caches upstream tool schemas for 5 minutes (`MCPTOON_CACHE_TTL`) and stops any single upstream call after 30 seconds (`MCPTOON_CALL_TIMEOUT`).
What it needs
| Runtime | Python 3.10+ |
|---|
Python 3.10 or later (pyproject.toml), installed with pipx, pip or a virtualenv; the README advises pipx or a venv over the system Python on Linux and Homebrew. The gateway only has something to pass through once servers are added to its config (`mcptoon add`, `mcptoon install` or `mcptoon quickstart`); each of those upstream servers brings its own runtime (Node for npx servers, and so on) and its own keys.
Limits
It is a front for other MCP servers: its own tools manage and report on them, and all real work happens in the upstream servers you add. Under the default compact exposure the client sees nine tools, not your upstream ones, so a client whose tool panel reads the list, or a model that will not ask for the manifest, needs the `full` exposure setting. Calls to tools whose names contain delete, drop or purge are refused through the gateway; the docs point to the CLI's `--destructive` flag to run them. Each upstream call stops after 30 seconds unless `MCPTOON_CALL_TIMEOUT` raises it. The token figures (71,929 to 581) come from a synthetic 255-tool sample; `mcptoon bench` measures your own setup.
Who it suits
Suits someone running many MCP servers across several agents who wants one config entry and a smaller tool list in each agent, and is willing to let mcptoon rewrite agent configs (quickstart moves existing servers behind the gateway by default; `--dry` previews and `mcptoon restore` undoes it). With one or two servers the extra layer buys little. It is not from any vendor whose product it reaches, and it adds a step (manifest, inspect, call) before every upstream tool use, which some models handle less reliably than a direct tool list.
Tools 9
mcptoon_manifest- Lists the upstream tools behind the gateway by name, grouped by server
mcptoon_servers- Shows each configured upstream server with its transport, tool count and load status
mcptoon_health- Reports the gateway's version, config path, server and tool counts and uptime
mcptoon_usage- Reports tokens saved and calls made in the current session
mcptoon_skills- Lists the agent skills indexed on the machine with a one-line summary each
mcptoon_resolve_skills- Ranks the indexed skills against a task description, best match first
mcptoon_inspect- Returns one upstream tool's full input schema without running it
mcptoon_call- Runs any upstream tool by its namespaced server_tool name
mcptoon_retrieve- Fetches the full text of a result the gateway compressed, by its handle