{"slug": "show-hn-mcptoon-token-efficient-mcp-cli-client", "title": "Show HN: Mcptoon – Token-efficient MCP CLI client", "summary": "Developer activeing123 released mcptoon v0.2.0, a token-efficient MCP CLI client that reduces MCP tool discovery token usage from 10,000+ to 350 tokens by outputting TOON (Token-Optimized Object Notation) instead of JSON. The zero-dependency, 50KB Python tool works with any AI agent and claims up to 97% token savings for tool discovery, addressing the 40,000-70,000 token overhead typical in MCP conversations.", "body_md": "**MCP tool discovery costs 10,000+ tokens. mcptoon costs 350.**\n\n*One MCP client for every AI agent. Cross-platform. Zero dependencies. Battle-tested with 255+ tools.*\n\n**If this saves you tokens, please star the repo — it helps others discover it.**\n\n[English](/activeing123/mcptoon/blob/main/README.md) | [中文文档](/activeing123/mcptoon/blob/main/README.zh-CN.md) | [Report Bug](https://github.com/activeing123/mcptoon/issues) | [Request Feature](https://github.com/activeing123/mcptoon/issues)\n\n** What's new in v0.2.0** — stdin support, doctor command, tool poisoning guard, fuzzy match, cross-agent format export\n\nEvery MCP-enabled conversation burns tokens on **syntax, not data**:\n\n- Your agent connects to 5 MCP servers. Listing their tools:\n**~10,000 tokens** of JSON. - Your agent calls 20 tools. Each returns 500-3,000 tokens wrapped in\n`{\"content\":[{\"type\":\"text\",\"text\":\"...\"}]}`\n\n. - Total MCP overhead:\n**40,000-70,000 tokens** before any actual thinking happens.\n\nOn a 128K context window, that's **30-55% gone**. Not on work. On syntax.\n\nmcptoon is a CLI client that connects to any MCP server (stdio or HTTP) and outputs **TOON** (Token-Optimized Object Notation) instead of JSON.\n\n| Operation | JSON tokens | mcptoon tokens | Savings |\n|---|---|---|---|\n| Tool discovery (96 tools) | ~2,000 | ~60 | 97% |\n| Tool result (structured data) | ~800 | ~350 | 56% |\n| Tool result (raw HTML/text) | ~1,000 | ~900 | 10% |\n\nZero dependencies. Pure Python. 50KB. Works with **every AI agent** — Claude Code, Codex, OpenCode, Cursor, CatPaw, anything that runs shell commands.\n\n**JSON (287 tokens)** — what every other MCP client returns:\n\n```\n[\n  {\"name\": \"search_web\", \"description\": \"Search the web for information\",\n   \"inputSchema\": {\"type\": \"object\", \"properties\": {\"query\": {\"type\": \"string\", \"description\": \"Search query\"}, \"num_results\": {\"type\": \"number\", \"default\": 5}}, \"required\": [\"query\"]}},\n  {\"name\": \"fetch_url\", \"description\": \"Fetch content from a URL\",\n   \"inputSchema\": {\"type\": \"object\", \"properties\": {\"url\": {\"type\": \"string\"}}, \"required\": [\"url\"]}}\n]\n```\n\n**TOON (5 tokens)** — what mcptoon returns:\n\n```\nsearch_web fetch_url\n```\n\n98% reduction for tool discovery, 60% for full schema, zero information lost.\n\n```\npip install mcptoon\n```\n\nZero dependencies. 50KB. Python 3.10+. Windows, macOS, Linux.\n\n```\nmcptoon init                          # Sample config: ~/.mcptoon/config.json\nmcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch\nmcptoon manifest --toon               # -> fetch:fetch\nmcptoon call fetch fetch '{\"url\":\"https://example.com\"}' --toon\nmcptoon call fetch fetch '{\"url\":\"https://example.com\"}' --json   # when you need JSON\n```\n\n| JSON | TOON | Why |\n|---|---|---|\n`{\"name\":\"search\",\"count\":3}` |\n`name:search|count:3` |\nPipes replace braces + quotes + colon |\n`[1, 2, 3]` |\n`1 2 3` |\nSpaces replace brackets + commas |\n`true` / `false` |\n`T` / `F` |\n1 char vs 4-5 |\n`null` |\n`∅` |\n1 symbol vs 4 chars |\n`\"line1\\nline2\"` |\n`line1↲line2` |\n↲ replaces escape sequence |\n`{\"a\":{\"b\":[1,2]}}` |\n`a:b:1_2` |\nRecursive compaction |\n\n| Flag | What you get | Token footprint |\n|---|---|---|\n`--toon` |\nCompact notation, full semantics | 40-60% less than JSON |\n`--compact` |\nTool names only, space-separated | 97% less than JSON |\n`--json` |\nStandard JSON (for scripts, CI) | Baseline |\n`--raw` |\nRaw response, no parsing | Full size |\n`--head N` |\nFirst N items only | Variable |\n`--max-chars N` |\nHard truncate at N chars | Variable |\n`--full` |\nDisable the default 4000-char truncation | Full size |\n\nSet `MCPTOON_AGENT_TYPE=claude`\n\nand every call auto-selects `--toon`\n\n.\n\nBattle-tested features from production use with 255+ MCP tools across 23+ servers:\n\nOS command-line limits (32,767 chars on Windows, ~128KB on Linux) break MCP calls with large content. Now you can pipe arguments via stdin:\n\n```\n# This fails on Windows if content > 32KB:\nmcptoon call fetch put '{\"content\":\"...huge...\"}'\n\n# This always works:\necho '{\"content\":\"...huge...\"}' | mcptoon call fetch put --stdin --toon\nmcptoon call fetch put --stdin --toon < payload.json\nbash\n$ mcptoon doctor\n  ✓ Python 3.12.0 (>=3.10 required)\n  ✓ Config: ~/.mcptoon/config.json (5 servers)\n  ✓ Cache dir: ~/.cache/mcptoon\n  ✓ fetch              [stdio]  1 tools\n  ✓ github             [stdio]  12 tools\n  ✗ myapi              [http]   ERROR: Connection refused\n  - MCPTOON_AGENT_TYPE not set (defaulting to auto)\n\n  5 checks, 1 issue(s)\nbash\n$ mcptoon discover\nDiscovered 3 server(s):\n\n  ✓ fetch                [stdio]   1 tools  ok\n  ✓ github               [stdio]  12 tools  ok\n  ✗ myapi                [http]    0 tools  error\n    └─ Connection refused\n```\n\nMCP servers return arbitrary content. A compromised server could inject instructions into your agent's context. mcptoon now detects and blocks common prompt injection patterns:\n\n``` bash\n$ mcptoon call malicious get_data '{}'\nError [TOOL_POISONING]: Tool result may contain prompt injection:\n  potential prompt injection detected: contains 'ignore previous instructions'\n```\n\nPatterns detected: instruction overrides, hidden `<!-- assistant:`\n\ndirectives, `[INST]`\n\n/`<<SYS>>`\n\ntags, data exfiltration attempts.\n\nTool names across MCP servers follow no naming convention. When you mistype:\n\n``` bash\n$ mcptoon call exa sarch '{\"query\":\"AI\"}'\nError [METHOD_NOT_FOUND]: Unknown tool: sarch\nDid you mean: search, search_all\n```\n\nExport your tool manifest for non-CLI agents:\n\n```\n# OpenAI function calling\nmcptoon manifest --format openai > functions.json\n\n# OpenAPI 3.0 spec\nmcptoon manifest --format openapi > openapi.json\n\n# MCP tools/list format\nmcptoon manifest --format mcp > mcp-tools.json\n```\n\n| mcptoon | mcp-cli | mcporter | raw MCP SDK | |\n|---|---|---|---|---|\n| Token savings | 97% manifest, 40-60% results |\n0% | 0% | 0% |\n| Works with all agents | yes (Claude Code, Codex, OpenCode, Cursor, any) |\nClaude only | Claude only | varies |\n| One config for all agents | yes |\nno | no | no |\n| Output formats | TOON + JSON + compact + openai + openapi + mcp |\nJSON | JSON | JSON |\n| Dependencies | 0 |\n5-20 | npm | 3-8 |\n| Dangerous-op blocking | yes | no | no | no |\n| Tool poisoning guard | yes |\nno | no | no |\n| Fuzzy match suggestions | yes |\nno | no | no |\n`--stdin` large payloads |\nyes |\nno | no | no |\n`doctor` self-diagnosis |\nyes |\nno | no | no |\n| Usage tracking | yes (local) | no | no | no |\n| Schema cache | yes (5min) | no | no | no |\n| Install size | ~50KB | ~50MB+ | ~30MB | ~10MB |\n| Platform support | Windows, macOS, Linux |\nLinux/macOS | macOS | varies |\n\nmcptoon is a CLI tool. If your agent can run shell commands, it can use mcptoon.\n\n| Agent | How to use |\n|---|---|\nClaude Code |\nWrite `mcptoon` commands in SKILL.md files |\nCodex (OpenAI) |\nAdd `mcptoon` to AGENTS.md |\nOpenCode |\nUse `mcptoon` in custom commands |\nCursor |\nAdd `mcptoon` to .cursorrules |\nCatPaw |\nWrite `mcptoon` commands in skill files |\nAny agent |\nIf it runs shell commands, it can call `mcptoon` |\n\nConfigure MCP servers **once** in `~/.mcptoon/config.json`\n\n. Every agent shares the same servers, the same tools, the same token savings.\n\n```\nexport MCPTOON_AGENT_TYPE=claude   # auto-select --toon\n# In ~/.claude/skills/mcp-tools/SKILL.md\nSearch the web: mcptoon call exa search '{\"query\":\"AI news\"}'\nList available tools: mcptoon manifest --toon\nFetch a URL: mcptoon call fetch fetch '{\"url\":\"https://example.com\"}'\n# In AGENTS.md or system prompt\nUse mcptoon to call MCP tools. It saves 60% tokens vs JSON.\n- List tools: mcptoon manifest --toon\n- Call a tool: mcptoon call <server> <tool> '{\"args\":\"here\"}' --toon\npython\nfrom mcptoon.client import MCPClient\nfrom mcptoon.output import toon\n\nwith MCPClient(stdio=[\"npx\", \"-y\", \"@modelcontextprotocol/server-fetch\"]) as c:\n    tools = c.list_tools()\n    print(toon(tools))         # compact TOON\n    result = c.call_tool(\"fetch\", {\"url\": \"https://example.com\"})\n    print(toon(result))\npython\nfrom mcptoon.router import register\n\n@register(\"my-database\", \"db\")\ndef handle_db(tool, args):\n    if tool == \"query\":\n        return {\"rows\": my_db.execute(args[\"sql\"])}\n    return None  # falls through to MCP\n# stdio (any npx MCP server)\nmcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch\nmcptoon add github --stdio npx -y @modelcontextprotocol/server-github\n\n# HTTP\nmcptoon add myapi --http http://localhost:3001/mcp --header \"Authorization: Bearer xxx\"\n```\n\nConfig lives at `~/.mcptoon/config.json`\n\n. Project-level override at `./.mcptoon.json`\n\n.\n\nmcptoon blocks operations that match dangerous patterns (`delete`\n\n, `drop`\n\n, `purge`\n\n, `wipe`\n\n, `kill`\n\n, etc.) unless you pass `--destructive`\n\n.\n\n``` bash\n$ mcptoon call db delete_table '{\"name\":\"users\"}'\nError [CONFIRMATION_REQUIRED]: Dangerous operation needs confirmation\n\n$ mcptoon call db delete_table '{\"name\":\"users\"}' --destructive\n# runs\nbash\n$ mcptoon usage\nTotal calls: 142\nSuccess rate: 138/142\nTokens (est): 84,200\n\nBy server:\n  fetch       89\n  github      53\n```\n\nStored locally at `~/.cache/mcptoon/usage.json`\n\n. Never transmitted.\n\n```\nsrc/mcptoon/\n├── cli.py        # CLI entry + arg parsing\n├── client.py     # MCPClient — stdio + HTTP transport\n├── router.py     # Tool routing, custom handlers, safety checks\n├── config.py     # Server config\n├── manifest.py   # Tool discovery with cache\n├── output.py     # TOON / JSON / compact rendering\n├── cache.py      # Schema cache (5-min TTL)\n├── usage.py      # Local usage tracking\n└── errors.py     # Structured error envelopes\n```\n\n~1,700 lines total. Zero third-party imports.\n\n**No telemetry.** No analytics, no crash reports, no phone-home.**No credential storage.** API keys pass through from your config or env vars.**No dependencies.** Pure Python stdlib. No supply chain to audit.\n\nFound a vulnerability? Email `security@activeing123.github.io`\n\n. See [SECURITY.md](/activeing123/mcptoon/blob/main/SECURITY.md).\n\nApache 2.0. See [LICENSE](/activeing123/mcptoon/blob/main/LICENSE) and [NOTICE](/activeing123/mcptoon/blob/main/NOTICE).\n\n```\ngit clone https://github.com/activeing123/mcptoon.git\ncd mcptoon\npip install -e . --no-build-isolation\npip install pytest pytest-cov\npython -m pytest tests/ -v   # 98 tests, 0.09s\n```\n\nZero dependencies is a hard rule. New features need tests. See [CONTRIBUTING.md](/activeing123/mcptoon/blob/main/CONTRIBUTING.md).\n\n*mcptoon is an independent third-party MCP client. Not affiliated with Anthropic.*\n\n**Found this useful? Star the repo to help others find it.**", "url": "https://wpnews.pro/news/show-hn-mcptoon-token-efficient-mcp-cli-client", "canonical_source": "https://github.com/activeing123/mcptoon", "published_at": "2026-08-11 05:26:58+00:00", "updated_at": "2026-08-11 09:41:53.349067+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "artificial-intelligence"], "entities": ["activeing123", "mcptoon", "MCP", "TOON", "Claude Code", "Codex", "OpenCode", "Cursor"], "alternates": {"html": "https://wpnews.pro/news/show-hn-mcptoon-token-efficient-mcp-cli-client", "markdown": "https://wpnews.pro/news/show-hn-mcptoon-token-efficient-mcp-cli-client.md", "text": "https://wpnews.pro/news/show-hn-mcptoon-token-efficient-mcp-cli-client.txt", "jsonld": "https://wpnews.pro/news/show-hn-mcptoon-token-efficient-mcp-cli-client.jsonld"}}