mcptoon: Token-Efficient MCP CLI Client

Reducing MCP Token Overhead with mcptoon

mcptoon is a cross-platform CLI client designed to minimize the token cost associated with the Model Context Protocol (MCP). By replacing standard JSON responses with a proprietary compact notation called TOON (Token-Optimized Object Notation), mcptoon claims to reduce tool discovery costs by up to 97% and tool result overhead by 40-60%.

The Problem: JSON Syntax Bloat

Standard MCP-enabled conversations often consume significant tokens on structural syntax rather than actual data. According to the project documentation, connecting to five MCP servers to list tools can cost approximately 10,000 tokens of JSON. When agents call multiple tools, the results are wrapped in verbose JSON structures (e.g., {"content":[{"type":"text","text":"..."}]}), which can consume 30-55% of a 128K context window before the AI begins processing the actual information.

The Solution: TOON (Token-Optimized Object Notation)

mcptoon connects to MCP servers via stdio or HTTP and converts JSON output into TOON. This notation uses specific substitutions to reduce character and token counts:

JSON	TOON	Logic
{"name":"search","count":3}	`name:search	count:3`
[1, 2, 3]	1 2 3	Spaces replace brackets and commas
true / false	T / F	Single character replacement
null	∅	Single symbol replacement
"line1\nline2"	line1↲line2	Special symbol replaces escape sequences
{"a":{"b":[1,2]}}	a:b:1_2	Recursive compaction

Performance Comparison

Operation	JSON tokens	mcptoon tokens	Savings
Tool discovery (96 tools)	~2,000	~60	97%
Tool result (structured data)	~800	~350	56%
Tool result (raw HTML/text)	~1,000	~900	10%

Integration and Compatibility

mcptoon is a CLI tool with zero third-party dependencies, written in pure Python (3.10+). It is compatible with any AI agent capable of executing shell commands, including Claude Code, Cursor, Codex, and OpenCode.

Deployment Examples

• Claude Code: Users can write mcptoon commands in SKILL.md files and set MCPTOON_AGENT_TYPE=claude to automatically select the --toon output format.
• Cursor: The tool can be added to .cursorrules.
• Codex (OpenAI): Instructions can be added to AGENTS.md or the system prompt to use mcptoon manifest --toon for tool listing.

Key Features and Safety

• Unified Configuration: MCP servers are configured once in ~/.mcptoon/config.json, allowing multiple agents to share the same toolset.
• Safety Blocking: The client blocks operations matching dangerous patterns (e.g., delete, drop, purge) unless the --destructive flag is passed.
• Usage Tracking: Local tracking of total calls, success rates, and estimated token savings is stored in ~/.cache/mcptoon/usage.json.
• Schema Caching: Includes a schema cache with a 5-minute TTL to further reduce discovery overhead.

Technical Community Critique

While the project emphasizes token savings, several developers in the Hacker News community raised concerns regarding the actual efficacy of the TOON notation:

• Tokenization vs. Characters: Critics argue that the author may be confusing character count with token count. For example, users noted that true/false and null are often single tokens in modern tokenizers, meaning replacing them with T/F or ∅ provides no benefit or may even increase token count due to the use of non-ASCII Unicode symbols.
• Information Loss: Some users pointed out that the --compact mode, which returns only tool names, removes critical descriptions and input schemas, potentially leading to LLM hallucinations or incorrect tool calls.
• Alternative Approaches: Some developers suggested that returning tool names with their arguments (e.g., search_web(query)) is more effective than listing names alone to prevent argument hallucination.

"I think that some of these choices... show that the author has not investigated how tokenization works. Tokenization is not some black box, you can run tokenizers and check them."

Quick Start Guide

# Install
pip install mcptoon

# Initialize and add a server
mcptoon init
mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch

# List tools in TOON format
mcptoon manifest --toon

# Call a tool
mcptoon call fetch fetch '{"url":"https://example.com"}' --toon