# Token-Efficient MCP Tool Use

> Modern agents already defer MCP tool schemas, so token-efficient MCP use now comes down to compacting what tools return before it lands in context.

Source: https://tokenade.net/en/articles/token-efficient-mcp-tool-use · Updated: 2026-10-16

## What is token-efficient MCP tool use?

Token-efficient MCP tool use means you compact what a tool hands back before it lands in context, and you only pay [tokens](https://tokenade.net/en/glossary/token) for a tool's schema when the agent actually needs it. The second half is now largely handled for you: Claude Code defers [MCP](https://tokenade.net/en/glossary/mcp) tool definitions by default through tool search, and other current agents defer tool loading too. The first half is not. Whatever a tool returns still gets dumped into the [context window](https://tokenade.net/en/glossary/context-window) unfiltered, and then rides along in history on every later turn. That is the cost you can mostly stop paying.

I build token tooling for a living, and MCP is where I see the most waste per unit of effort to fix. The protocol is great — it's the cleanest way I've found to give an agent real capabilities. But tool results come back raw by default, as if tokens were free, and they are emphatically not free. This piece is the practitioner's version of the fix: what to do at the output layer, what is left to check at the schema layer, and where a tool can just handle it so you don't have to think about it.

This is a spoke off the broader question of [how to reduce AI coding agent token usage](https://tokenade.net/en/articles/reduce-ai-coding-agent-token-usage). If you want the whole menu of levers, start there. Here I'm staying narrow on MCP.

## Why do MCP tools cost more tokens than you think?

MCP tools cost more than you think because what they return stays in the transcript. A coding session isn't one request; it's dozens or hundreds of round-trips, and every tool call appends its raw result to the running history that each later turn re-sends.

The schema side used to be the headline problem. Early agents sent every connected server's full tool manifest on every turn, and a couple of heavyweight servers could eat a meaningful slice of the window. That is no longer the default: Claude Code's tool search keeps only tool names in context and loads a schema when the agent reaches for it, and other current agents defer tool loading as well. It still bites in a few setups, covered below.

The output side is where the money goes now, and it's sneakier. Tools love to return JSON — and JSON is verbose, repetitive, and full of fields the agent will never read. A "list files" call can hand back a few thousand tokens of metadata so the model can use one path. A web fetch returns the whole DOM when the agent wanted one heading. None of that is wrong, exactly; it's just unfiltered, and unfiltered is expensive. On Sonnet 5 ($2 / $10 per MTok) or Haiku 4.5 ($1 / $5) the absolute numbers shrink, and on GPT-5.5 ($5 / $30) the output side bites harder because output is priced at a premium — but the ratio holds across all of them: you're paying continuously for bytes the model doesn't use. The numbers behind this are collected in our [AI coding agent token costs](https://tokenade.net/en/stats/ai-coding-agent-token-costs) breakdown, and the per-model rates in our [LLM API token pricing](https://tokenade.net/en/stats/llm-api-token-pricing) reference.

## How do you cut the output cost?

You cut the output cost with [output filtering](https://tokenade.net/en/glossary/output-filtering) — compacting a tool's result down to the bytes the agent will actually use before that result enters context. Most of what a tool emits is structure, repetition, and fields nobody reads, and you can fold that away without losing the signal.

In practice this means a few things stacked together:

- **Drop the boilerplate.** Pagination wrappers, timestamps, ETags, repeated keys across array elements — none of that helps the model reason. [Context compression](https://tokenade.net/en/glossary/context-compression) trims it.
- **Deduplicate.** Tool output is full of near-identical rows. Collapsing them to a representative plus a count keeps the meaning at a fraction of the tokens.
- **Summarise the long tail.** When a fetch returns a 40 KB document and the agent wanted one section, returning the section plus a one-line map of the rest beats returning the whole thing.

For codebase work specifically, the biggest output win is upstream of all this: don't dump whole files at all. Use [semantic code search](https://tokenade.net/en/glossary/semantic-code-search) to retrieve the few functions that match the intent — backed by [embeddings](https://tokenade.net/en/glossary/embeddings) over the repo, the same [RAG](https://tokenade.net/en/glossary/rag) idea everyone uses for docs — instead of reading entire files into context so the model can ignore 90% of them. A "read file" tool is a token firehose; a "find the code that does X" tool is a teaspoon.

## What about the schema cost?

On a current Claude Code setup, there is little left to do: tool search defers MCP tool definitions by default for Claude 4.5 and later models, and most other agents now defer tool loading too. It still matters in a few cases, which [lazy MCP loading](https://tokenade.net/en/articles/lazy-mcp-loading) covers in detail: behind a third-party API proxy (Claude Code turns tool search off there unless you set `ENABLE_TOOL_SEARCH`), for servers marked `alwaysLoad`, on older models and in agents without tool search. Run `/context` once to see which case you're in. If your manifests do load upfront, prune the servers you rarely use and prefer CLIs like `gh` where they exist. Our [best MCP servers for Claude Code](https://tokenade.net/en/articles/best-mcp-servers-for-claude-code) ranking helps decide which servers earn their place.

## How to apply token-efficient MCP today

You can get from "leaking tokens" to "paying for what you use" in an afternoon, roughly in order of effort:

1. **Measure first.** Run a normal session and look at how big your average tool result is, and how many input tokens land *before* your first real instruction. Eyeballing isn't measuring. Our [measure agent token usage](https://tokenade.net/en/articles/measure-agent-token-usage) walk-through covers this, and you can sanity-check rough figures with the [token counter](https://tokenade.net/en/micro-tools/token-counter) and the [LLM token cost calculator](https://tokenade.net/en/micro-tools/llm-token-cost-calculator).
2. **Filter the output side.** Where you control a tool, return the minimum useful shape. Where you don't, put a compacting layer in front of it.
3. **Confirm your agent defers schemas.** If `/context` shows manifests loading upfront, see the exceptions above and disconnect the servers you use occasionally.
4. **Let a layer do it automatically.** Manual discipline is real work and you'll get it wrong on a busy day. This is where [Tokenade](https://tokenade.net/en) comes in: its MCP proxy sits between your agent and its MCP servers (`tokenade mcp-wrap install` wraps them in one command) and compacts what the tools return before it hits context, with dedicated compactors for GitHub and GitLab, browser automation (Playwright, Puppeteer, Chrome), filesystem, Git, memory and databases (Postgres, SQLite, MySQL, Supabase, DuckDB), and a generic shape-aware compactor for every other server. Screenshots and images pass untouched, and the full result stays recoverable if the agent needs a detail. It folds noisy command output the same way, swaps whole-file reads for semantic search, and opens a local report of the savings (`tokenade dashboard`) so you can see what each tool saved. It works the same way across Claude Code, Cursor, Codex, Copilot, and Windsurf, and it's free and open source (MIT/Apache-2.0). Compaction runs entirely on your own machine, so none of that traffic leaves it.

If you only do one thing from this list, measure, because the size of raw tool output is usually large enough that you'll feel slightly annoyed you weren't tracking it sooner.

## What goes wrong (anti-patterns)

The failure modes here mostly come from confusing "connected" with "free" and "returned" with "needed." A few to watch for:

- **Trusting raw output.** Letting tools dump unfiltered JSON into context is the most expensive MCP habit today. The model reads a fraction of it and you pay for all of it, on every turn it stays in history. Compact before context, not after.
- **Filtering too hard.** Over-aggressive output trimming can drop the one field the agent actually needed and cause a re-call — which costs more than the bytes you saved. Filter the boilerplate and the long tail; keep the signal, and keep the full result recoverable.
- **Assuming every setup defers schemas.** A third-party proxy, an `alwaysLoad` flag or an older model brings back upfront loading without telling you. Check `/context` once.
- **Assuming caching makes it free.** [Prompt caching](https://tokenade.net/en/glossary/prompt-caching) cuts re-send cost to roughly 10% of input, which is excellent — but it's cold on the first turn, breaks when the prefix changes, and never beats not sending the bytes at all. It's a discount, not an exemption. (If you keep hitting limits anyway, that's usually a [rate-limit](https://tokenade.net/en/glossary/rate-limit) problem, and fewer tokens helps there too.)

The honest summary: the manifest problem got fixed where it belonged, inside the agents. What's left is the tools fire-hosing raw output into context because it was the path of least resistance. Token-efficient MCP today is mostly one structural fix, compact output before it lands, and unlike a lot of [context engineering](https://tokenade.net/en/articles/context-engineering), it's something a tool can just do for you while you get on with shipping.

---

**See also:**
- [How to reduce AI coding agent token usage](https://tokenade.net/en/articles/reduce-ai-coding-agent-token-usage)
- [Lazy MCP loading](https://tokenade.net/en/articles/lazy-mcp-loading)
- [Best MCP servers for Claude Code](https://tokenade.net/en/articles/best-mcp-servers-for-claude-code)
- [Claude Code MCP: how to set it up](https://tokenade.net/en/articles/claude-code-mcp-setup)
- [Tool calling (function calling)](https://tokenade.net/en/glossary/tool-calling) — the primitive every MCP server is built on
- [MCP — glossary](https://tokenade.net/en/glossary/mcp)
- [Output filtering — glossary](https://tokenade.net/en/glossary/output-filtering)