Your AI Agent Reads a 300-Page Book Before It Answers You

Every prompt you send starts with homework. Before Claude Code or Cursor even looks at your question, it reads the full JSON schema of every MCP tool it might call. On my machine that was 255 tools across 50 servers. I measured it with tiktoken cl100k_base: 71,929 tokens. A 300-page book, read cover to cover, every session, before your agent ever thinks about what you asked.

That same tool listing now costs me 123 tokens. A sticky note. Same tools, same capabilities, and you can reproduce the number on your own config with one command.

This is the story of mcptoon, a zero-dependency CLI, and the three problems it fixed that I never planned to touch.

Problem 1: four agents means four config files

Claude Desktop wants claude_desktop_config.json. Claude Code wants .claude.json. Cursor wants .cursor/mcp.json. Cline, Windsurf and VS Code Copilot each have their own shape too. Add a fetch server in Cursor, forget Claude. Fix a path in Claude, break Cursor. Repeat weekly.

mcptoon's answer is one file. ~/.mcptoon/config.json becomes the single source of truth, and mcptoon sync writes native config into every agent it detects. It merges instead of overwriting, so servers you configured by hand stay put. Run mcptoon sync --watch and drift detection catches external edits before they bite.

The part I like most: agents need zero setup. mcptoon is a program your agent already knows how to run. There is no mcpServers entry, no plugin API, nothing to register and nothing to restart. One line in CLAUDE.md and your agent drives every MCP server through the shell. That also means it reaches places MCP cannot: shell scripts, CI jobs, cron, aider, terminal-only boxes.

Problem 2: the token tax

Here is the mechanism behind that 300-page book. When your agent asks "what tools exist?", native MCP ships the full schemas. Every parameter, every description, every nested properties block. Multiply by 255 tools and you get 71,929 tokens sitting in your context before a single tool call.

mcptoon's manifest command answers the same question with a name index:

$ mcptoon manifest --compact
fetch: fetch(url) · github: search_repos(q), get_file(repo, path) · sqlite: query(sql)

Schemas stay on disk. They never enter the context at all. That is the difference between this and compression: compression still ships the payload and unpacks it later, so the cost just moves. Here the cost is deleted.

It's a dial, not a switch. The same 255-tool config measures 8,282 tokens with --slim (names plus parameter types, minus 88.5%) and 123 with --compact (names only, minus 99.8%). Full JSON stays available with --json whenever you want zero ambiguity. Reproduce it yourself: mcptoon manifest --compact --tokens.

Problem 3: configured is not alive

A 2026 community audit found 52% of published MCP servers unreachable. Half the servers in people's configs are dead weight, and nothing in a JSON file tells you which ones.

mcptoon health checks every server, shows latency, and exits 1 in CI when something is dead:

── mcptoon health: 3/5 alive ──────────────
  ✓ fetch     [stdio]  1 tool     120ms  ok
  ✗ brave     [stdio]  0 tools  10002ms  timeout
  ✓ github    [http]  12 tools    340ms  ok

And because MCP servers run code on your machine and return arbitrary text into your agent's context, every result passes through checks for prompt injection ("ignore previous instructions" buried in tool output), credential leaks (sk-..., AKIA..., ghp_... patterns) and dangerous operations like delete or drop unless you pass --destructive.

No telemetry. No analytics. Nothing phones home.

The objections I hear

"Isn't this just TOON compression?" No. The headline number comes from architecture: full schemas simply are not sent. Optional TOON encoding of tool results saves another 30 to 40% and it is off by default.

"Didn't Claude Code already defer tool loading?" Deferred loading decides when definitions load. mcptoon decides what a listing costs, in every agent at once, and adds sync, health and security on top. They stack fine.

"Why a CLI?" Because the shell is the one interface every agent already speaks. Zero dependencies also means the whole supply chain is about 6,800 lines of readable Python, with 569 tests staying green in CI.

Try it

pip install mcptoon
mcptoon quickstart    # finds servers you already configured
mcptoon demo          # live side-by-side: JSON vs mcptoon, real token counts

mcptoon speaks the latest MCP spec (2026-07-28) with full backward compatibility, runs on Windows, macOS and Linux, and ships under Apache 2.0. Repo: https://github.com/activeing123/mcptoon

If your agent is reading a 300-page book before it answers you, that is context you paid for and never used. Make it a sticky note.