# mcptoon

> Token-efficient MCP CLI client that compresses tool discovery responses by up to 99.87% using TOON format. Zero dependencies, Apache 2.0, works with any AI agent that can run shell commands.

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.

## Features
- Token-efficient MCP tool discovery (up to 99.87% token reduction)
- TOON (Token-Oriented Object Notation) encoding — round-trip safe
- SLIM format for ultra-compact tool schemas (93% smaller than JSON)
- Compact mode returning tool names only (97% smaller than JSON)
- Zero third-party dependencies — pure Python stdlib
- 23 security-audited MCP server profiles included
- Credential leak detection — blocks exposed API keys before context injection
- Prompt injection guard — scans tool results for injection patterns
- Dangerous-op blocking — requires --destructive flag for delete/drop/purge
- Agent self-service — agents can add MCP servers themselves via CLI
- One config file shared across all agents (~/.mcptoon/config.json)
- Lazy server startup — MCP servers only spawn when actually called
- Schema cache with 5-minute TTL
- Cross-agent export (--format openai|openapi|mcp)
- Shell completion for bash, zsh, fish, PowerShell
- Doctor command for self-diagnosis of Python, config, and connectivity
- Discover command for server health checks with tool counts
- Fuzzy match with 'Did you mean?' suggestions
- stdio and HTTP MCP transport support
- Docker support
- Python API (MCPClient, toon_encode, toon_decode)
- Local-only usage tracking and token estimates
- No telemetry, no phone-home

## Integrations
Claude Code, Codex (OpenAI), Cursor, OpenCode, CatPaw, Puppeteer MCP, Playwright MCP, GitHub MCP, Firecrawl MCP, Exa MCP, Brave Search MCP, Filesystem MCP, Memory MCP, SQLite MCP, Postgres MCP, Slack MCP, Notion MCP, Git MCP, GitLab MCP, Tavily MCP, Google Maps MCP, Docker MCP, AWS MCP, Cloudflare MCP, tmux MCP, npx, Docker

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
0.3.0

## Links
- Website: https://pypi.org/project/mcptoon/
- Documentation: https://github.com/activeing123/mcptoon
- Repository: https://github.com/activeing123/mcptoon
- EveryDev.ai: https://www.everydev.ai/tools/mcptoon