mcptoon

mcptoon is an open-source CLI tool that solves a core scaling problem with the Model Context Protocol (MCP): every MCP-enabled agent loads all tool schemas into the context window before any work starts, consuming tens of thousands of tokens before a single question is asked. Built by developer cxh and published on PyPI under Apache 2.0, mcptoon keeps MCP server configurations on disk and delivers only compact, token-optimized output to the agent's context.

What It Is

mcptoon is a command-line MCP client written in pure Python (zero third-party dependencies, ~50KB installed) that acts as a token-efficient intermediary between AI agents and MCP servers. Instead of injecting full JSON schemas into the context window, agents run mcptoon shell commands and receive compressed output in TOON, SLIM, or compact formats. The tool supports stdio and HTTP MCP transports, works on Windows, macOS, and Linux, and requires Python 3.10 or later.

The Token Problem It Solves

Standard MCP clients inject full JSON schemas for every configured server into the agent's context at startup. According to the project's own benchmarks (tiktoken-verified), 255 tools across 23 servers produce 90,804 JSON tokens — mcptoon's compact mode returns the same tool list in 117 tokens, a 99.87% reduction. The project documents several output formats with measured savings:

• --compact: Tool names only, space-separated — ~97% fewer tokens than JSON
• --slim: Ultra-compact schemas (tool|param:type*) — 93% fewer tokens
• --toon: Standard TOON (Token-Oriented Object Notation) — 51% fewer tokens, round-trip safe
• --mcptoon: Legacy pipe-separated format — 61% fewer tokens, round-trip safe
• --json: Standard JSON baseline for scripts and CI

Three-Layer Architecture

mcptoon decouples the CLI, server profiles, and actual MCP servers into three independent layers. The CLI (~50KB, zero deps) runs in the agent's shell. Layer 2 consists of ~1KB JSON profile files describing how to connect to each server — 23 security-audited profiles ship with the package covering fetch, GitHub, Exa, Brave Search, Firecrawl, filesystem, memory, Puppeteer, Playwright, Postgres, Slack, Notion, Git, GitLab, Tavily, Google Maps, Docker, AWS, Cloudflare, and tmux. Layer 3 is the actual MCP server processes, which spin up lazily only when mcptoon call runs — 100 servers configured means 0 running until needed.

Security Features

Every bundled profile declares its security posture with explicit credential_safe, env_vars_required, and permissions fields. At runtime, mcptoon applies three security layers:

• Dangerous-op guard: Blocks delete/drop/purge/kill operations by default unless --destructive is passed
• Prompt injection guard: Scans tool results for patterns like ignore previous instructions or [INST] before they reach the agent
• Credential leak guard: Scans results for exposed API keys, AWS keys, GitHub PATs, OpenAI/Anthropic keys, Slack tokens, JWTs, and private keys — blocks and masks them before context injection

Cross-Agent Compatibility

Because mcptoon is a CLI tool rather than an SDK or plugin, any agent that can run shell commands can use it without per-agent MCP configuration. The project documents integration paths for Claude Code (SKILL.md), Codex (AGENTS.md), Cursor (.cursorrules), OpenCode, and CatPaw. A single ~/.mcptoon/config.json file is shared across all agents, with a project-level override at ./.mcptoon.json. Agents can also self-serve — running mcptoon add github ... themselves mid-task without human intervention.

Update: v0.3.0 — tiktoken-verified TOON

Version 0.3.0 was published on August 12, 2026, and is the current release. The release name "tiktoken-verified TOON" reflects the addition of formal token-count verification using OpenAI's tiktoken library (o200k_base / cl100k_base encodings). The project moved from 0.1.0 to 0.3.0 across four releases in two days (August 11–12, 2026), indicating rapid early iteration. The GitHub README for the main branch documents 309 tests and ~3,000 lines of code, up from 187 tests and ~2,500 lines in the PyPI 0.3.0 description, suggesting active development beyond the published release. The project also added a Python API (MCPClient, toon_encode, toon_decode) and Docker support in recent iterations.