mcptoon: Een token-efficiënte MCP CLI-client

Het probleem

Bij elke MCP-compatibele conversatie worden veel tokens verspild aan syntaxis in plaats van aan data:

• Wanneer een agent verbinding maakt met 5 MCP-servers, kost het opsommen van hun tools ongeveer 10.000 tokens aan JSON.
• Wanneer een agent 20 tools aanroept, retourneert elke tool tussen de 500 en 3.000 tokens, verpakt in {"content":[{"type":"text","text":"..."}]}.

De totale MCP-overhead bedraagt hiermee vaak 40.000 tot 70.000 tokens voordat er überhaupt sprake is van daadwerkelijk denkwerk. Bij een contextvenster van 128K gaat er dus 30% tot 55% verloren aan syntaxis in plaats van aan productieve arbeid.

De oplossing

mcptoon is een CLI-client die verbinding maakt met elke MCP-server (via stdio of HTTP) en TOON (Token-Optimized Object Notation) outputt in plaats van JSON.

Besparingen in de praktijk

Operatie	JSON tokens	mcptoon tokens	Besparing
Tool discovery (96 tools)	~2.000	~60	97%
Tool resultaat (gestructureerde data)	~800	~350	56%
Tool resultaat (ruwe HTML/tekst)	~1.000	~900	10%

mcptoon is geschreven in pure Python, is slechts 50KB groot en heeft geen externe afhankelijkheden. Het werkt met elke AI-agent die shell-commando's kan uitvoeren, zoals Claude Code, Codex, OpenCode, Cursor en CatPaw.

Voorbeeld: JSON vs. TOON

JSON (287 tokens) — wat de meeste MCP-clients retourneren:

[
{"name": "search_web", "description": "Search the web for information",
"inputSchema": {"type": "object", "properties": {"query": {"type": "string", "description": "Search query"}, "num_results": {"type": "number", "default": 5}}, "required": ["query"]}},
{"name": "fetch_url", "description": "Fetch content from a URL",
"inputSchema": {"type": "object", "properties": {"url": {"type": "string"}}, "required": ["url"]}}
]

TOON (5 tokens) — wat mcptoon retourneert: searchweb fetchurl

Dit resulteert in een reductie van 98% voor tool-discovery en 60% voor volledige schema's, zonder dat er informatie verloren gaat.

Snelstart

Installatie:

pip install mcptoon

Vereisten: Python 3.10+. Ondersteunt Windows, macOS en Linux.

Basiscommando's:

mcptoon init                          # Maakt voorbeeldconfiguratie aan: ~/.mcptoon/config.json
mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch
mcptoon manifest --toon               # Output: fetch:fetch
mcptoon call fetch fetch '{"url":"https://example.com"}' --toon
mcptoon call fetch fetch '{"url":"https://example.com"}' --json   # Gebruik JSON wanneer nodig

Hoe TOON werkt

JSON	TOON	Reden
{"name":"search","count":3}	`name:search\	count:3`	Pipes vervangen accolades, quotes en colons
[1, 2, 3]	1 2 3	Spaties vervangen brackets en komma's
true / false	T / F	1 karakter vs 4-5 karakters
null	`�
`	1 symbool vs 4 karakters
"line1\nline2"	line1<0xE2><0x86><0xB2>line2	<0xE2><0x86><0xB2> vervangt escape-sequenties
{"a":{"b":[1,2]}}	a:b:1_2	Recursieve compactering

Output-formaten

Vlag	Resultaat	Token-voetafdruk
--toon	Compacte notatie, volledige semantiek	40-60% minder dan JSON
--compact	Alleen toolnamen, gescheiden door spaties	97% minder dan JSON
--json	Standaard JSON (voor scripts, CI)	Baseline
--raw	Ruwe respons, geen parsing	Volledige grootte
--head N	Alleen de eerste N items	Variabel
--max-chars N	Harde afkap op N karakters	Variabel
--full	Schakelt standaard afkap van 4000 tekens uit	Volledige grootte

Door MCPTOONAGENTTYPE=claude in te stellen, selecteert elke aanroep automatisch --toon.

Vergelijking met andere MCP-clients

Kenmerk	mcptoon	mcp-cli	mcporter	raw MCP SDK
Token besparing	97% manifest, 40-60% resultaten	0%	0%	0%
Werkt met alle agents	Ja (Claude Code, Codex, etc.)	Alleen Claude	Alleen Claude	Varieert
Eén config voor alle agents	Ja	Nee	Nee	Nee
Output formaten	TOON + JSON + compact	JSON	JSON	JSON
Afhankelijkheden	0	5-20	npm	3-8
Blokkeren gevaarlijke opdrachten	Ja	Nee	Nee	Nee
Gebruiksregistratie	Ja (lokaal)	Nee	Nee	Nee
Schema cache	Ja (5 min)	Nee	Nee	Nee
Installatiegrootte	~50KB	~50MB+	~30MB	~10MB
Platform support	Windows, macOS, Linux	Linux/macOS	macOS	Varieert

Integratie met AI-agents

mcptoon is een CLI-tool. Als een agent shell-commando's kan uitvoeren, kan deze mcptoon gebruiken. Configureer MCP-servers één keer in ~/.mcptoon/config.json, zodat elke agent dezelfde servers en tools deelt.

Implementatie per agent

• Claude Code: Voeg mcptoon-commando's toe aan SKILL.md bestanden.
• Codex (OpenAI): Voeg mcptoon toe aan AGENTS.md.
• OpenCode: Gebruik mcptoon in custom commands.
• Cursor: Voeg mcptoon toe aan .cursorrules.
• CatPaw: Schrijf mcptoon-commando's in skill-bestanden.

Voorbeelden van configuratie

Claude Code:

export MCPTOON_AGENT_TYPE=claude   # activeert automatisch --toon
# In ~/.claude/skills/mcp-tools/SKILL.md:
Search the web: mcptoon call exa search '{"query":"AI news"}'
List available tools: mcptoon manifest --toon
Fetch a URL: mcptoon call fetch fetch '{"url":"https://example.com"}'

Codex (OpenAI): In AGENTS.md of system prompt: "Gebruik mcptoon om MCP-tools aan te roepen. Dit bespaart 60% tokens t.o.v. JSON."

• Lijst tools: mcptoon manifest --toon
• Roep tool aan: mcptoon call <server> <tool> '{"args":"here"}' --toon

Python API

from mcptoon.client import MCPClient
from mcptoon.output import toon

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

Custom handlers (MCP volledig omzeilen)

from mcptoon.router import register

@register("my-database", "db")
def handle_db(tool, args):
    if tool == "query":
        return {"rows": my_db.execute(args["sql"])}
    return None  # valt terug op MCP

Configuratie

Servers toevoegen:

• stdio (voor elke npx MCP server):

mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch mcptoon add github --stdio npx -y @modelcontextprotocol/server-github

• HTTP:

mcptoon add myapi --http http://localhost:3001/mcp --header "Authorization: Bearer xxx"

Configuratiebestanden bevinden zich op ~/.mcptoon/config.json, met projectspecifieke overrides mogelijk via ./.mcptoon.json.

Veiligheid en Privacy

Veiligheid

mcptoon blokkeert operaties die overeenkomen met gevaarlijke patronen (zoals delete, drop, purge, wipe, kill) tenzij de vlag --destructive wordt meegegeven.

Voorbeeld: $ mcptoon call db deletetable '{"name":"users"}' → Error [CONFIRMATIONREQUIRED]: Dangerous operation needs confirmation

$ mcptoon call db delete_table '{"name":"users"}' --destructive → Voert operatie uit

Gebruiksstatistieken

Met $ mcptoon usage kun je lokale statistieken inzien (totaal aantal calls, succespercentage en geschatte tokens). Deze data wordt lokaal opgeslagen in ~/.cache/mcptoon/usage.json en nooit verzonden.

Privacy

• Geen telemetrie, analytics of crash-rapporten.
• Geen opslag van credentials; API-keys worden via configuratie of omgevingsvariabelen doorgegeven.
• Geen externe afhankelijkheden (alleen Python stdlib), wat de supply chain audit vereenvoudigt.

Architectuur

De broncode (~1.700 regels) is als volgt gestructureerd:

• cli.py: CLI entry-point en argument parsing.
• client.py: MCPClient — stdio + HTTP transport.
• router.py: Tool routing, custom handlers en veiligheidscontroles.
• config.py: Serverconfiguratie.
• manifest.py: Tool discovery met cache.
• output.py: TOON / JSON / compact rendering.
• cache.py: Schema cache (5-min TTL).
• usage.py: Lokale gebruiksregistratie.
• errors.py: Gestructureerde error envelopes.

Licentie en Bijdragen

Licentie: Apache 2.0.

Bijdragen:

1. Clone de repo: git clone https://github.com/activeing123/mcptoon.git
2. Installeer in editable mode: pip install -e . --no-build-isolation
3. Draai tests: python -m pytest tests/ -v

Harde regel: Er mogen geen externe afhankelijkheden worden toegevoegd. Nieuwe functies moeten voorzien zijn van tests.

mcptoon is een onafhankelijke third-party MCP-client en is niet gelieerd aan Anthropic.