mcp-token-optimizer

Stop paying for tool-response noise.

A self-hosted proxy between your AI agent and its MCP servers that shrinks every tool response: pruning, TOON encoding and local-LLM summarization, without changing what the agent can do.

Why

Every token an MCP tool returns is paid for, and fills the model's context window. Real tool output is mostly noise: null fields, hypermedia URLs, avatar and node ids, the same block repeated in two fields, ANSI and progress-bar spam, boilerplate prose. mto removes that noise before the model sees it, keeps an exact copy of anything it removed, and tells the agent how to get it back.

Local only, always. mto talks only to your own MCP servers and to a local Ollama on 127.0.0.1. No telemetry, no cloud model providers, nothing leaves your machine. The dashboard and its API bind to loopback, need a per-run token, and cannot run arbitrary commands. See Security and privacy.

Related MCP server: Delta-MCP

Results

Measured, reproducible, no LLM involved (npm run smoke, TESTING.md). Token counts are a model-agnostic estimate.

In that live A/B run, the three files the agent wrote from the optimized result were byte-identical to the original data (checked against a pre-optimization capture).

Highlights

• Lossless first. JSON ↔ TOON is emitted only after a verified round-trip; duplicate blocks become pointers; the canonical copy is never touched.

• Fail-open, never bigger. Any error, timeout or Ollama outage forwards the original; an optimized result is used only if it is strictly cheaper.

• mto_expand. Notes name exactly what was pruned; the agent can fetch the exact original (outline, JSON path, grep) on demand.

• Shadow mode. Measure real savings while forwarding the originals, so you can roll out with zero risk.

• Any MCP client. Stdio wrapper and local HTTP/SSE proxy; installs into VS Code Copilot, Claude, Cursor, Windsurf, Gemini CLI, Cline, Roo (JSONC-safe, reversible).

• Local summarization. Your Ollama model, your parameters, a hard latency budget and a fact-coverage guard; code and file reads are never summarized.

• Private by design. Binds to 127.0.0.1, no telemetry, credentials forwarded but never stored, optional secret redaction.

• Local dashboard. mto ui: overview, live traffic, connections, config editor, eval history, advisor and drift warnings, served by the daemon, no CDN (dashboard guide).

• Measurable. Capture, bench, compare and stats built in; 92 tests and a 24-check end-to-end smoke test.

Quick start

npm install -g @shubhamcodess/mcp-token-optimizer    # or clone and build; see the install guide
mto doctor                                           # checks config, Ollama and model
mto discover                                         # lists the MCP servers it found (read-only)
mto init --only <server> --apply                     # wrap one server; undo: mto uninstall --apply

No agent handy? npm run demo shows a tool call through the optimizer with sample data.

Roll out safely: set mode: shadow first. The proxy then measures savings but forwards the original responses, so nothing changes for your agent until you switch to active.

Full walkthrough: Getting started.

Documentation

Contributing

Contributions of all sizes are welcome: bug reports, docs, benchmark results, new agent integrations, pipeline improvements. Start with CONTRIBUTING.md and please read the Code of Conduct. Security issues: SECURITY.md.

License

Apache-2.0. Uses the official @toon-format/toon library for TOON, and Ollama for optional local summarization.