---
title: "How to reduce MCP token overhead in coding agents"
description: "MCP overhead can come from several places: tool definitions exposed to the model, large tool results, repeated results carried into later turns, and extra calls needed to find the right tool. Measure "
canonical: https://caveman.so/guides/mcp-token-overhead
last-updated: 2026-09-07
---

# How to reduce MCP token overhead in coding agents

MCP overhead can come from several places: tool definitions exposed to the model, large tool results, repeated results carried into later turns, and extra calls needed to find the right tool. Measure those separately before removing fields or disabling servers.

The protocol defines how hosts and servers exchange context and tools. It does not dictate exactly how each host loads that context into a model request. See [the MCP architecture](https://modelcontextprotocol.io/docs/learn/architecture) for that boundary.

## Find which layer is expensive

| Layer | What to inspect | Possible change |
| --- | --- | --- |
| Tool discovery | Tools visible to the model before work starts | Load a smaller relevant set where the host supports it |
| Tool schema | Descriptions, arguments, and repeated boilerplate | Tighten wording while preserving semantics |
| Tool result | Full documents, logs, rows, or browser trees | Filter, paginate, select, or compress eligible content |
| Conversation history | Earlier tool content repeated on later calls | Preserve useful context and recovery while reducing repetition |
| Tool selection | Failed or unnecessary calls | Improve names, descriptions, and discovery behavior |

A large list returned by MCP discovery is not automatically the same as a large model prompt. Some hosts load tools lazily or use search. Inspect the host behavior you actually run.

## Start with local session evidence

Caveman can inspect supported local agent sessions and rank token sinks:

```bash
npm install -g @caveman-ai/cli
caveman setup --install
caveman learn
caveman learn report --json
```

Read the report before applying anything. It identifies candidates; it does not prove a provider-billed saving. Coverage depends on the local sessions and formats available.

If you choose a suggested sink, preview the exact change using its real ID:

```bash
caveman learn apply YOUR_SINK_ID --dry-run
```

`YOUR_SINK_ID` is a placeholder from the report. Review scope and preserve required tool behavior before applying a change. The [learn documentation](https://docs.caveman.so/docs/skill/learn) explains the supported path.

## Reduce the tool set deliberately

Disable tools irrelevant to the current task where your host offers that control. Keep the configuration reversible and test a task that requires the tools you retain.

Avoid replacing precise tools with one vague “do everything” tool solely to reduce schema size. That can increase selection errors, hide permissions, and create repair turns.

When the host supports deferred discovery, test whether the agent finds the right tool with fewer total calls and input tokens. A small initial prompt is not a win if discovery takes five failed attempts.

## Preserve schema meaning

Shorten redundant prose, examples, or repeated boilerplate only after identifying what the model uses to choose and call the tool. Keep argument names, types, required fields, enums, and constraints intact.

Descriptions can contain necessary distinctions between read and write behavior or between similar tools. Removing those words may make the schema smaller and the agent worse.

Caveman has explicit tool-schema controls; broad stripping is not assumed on every path. Follow [proxy configuration](https://docs.caveman.so/docs/proxy/configure) for the supported options. Do not enable a transformation because an unrelated compressor produced a good ratio.

## Make tool results easier to use

Prefer source filtering and pagination when the tool owns structured data. Return the fields the task needs and label partial results honestly. Include a way to request the next page or inspect a specific item.

For large textual evidence, try a saved result with Caveman:

```bash
caveman shrink --file ./fixtures/mcp-tool-result.json
```

Inspect the output before integration. Verify any recovery handle and ask a follow-up that requires omitted content. Use [the compression guide](/guides/prompt-compression) for exact recovery and complete-task evaluation.

A consumer expecting a complete typed object cannot accept an arbitrary smaller view without a changed contract.

## Install recovery for the host that needs it

Once the required binary is available, the CLI can install the host's MCP configuration:

```bash
caveman tools mcp install claude --server caveman
```

Check the actual registered tool and run a recovery request. The local Caveman MCP server uses stdio; stdout must remain valid protocol traffic. A shell wrapper that prints a startup banner there can break the connection.

Store access matters. A handle created on one machine is not automatically recoverable by a remote agent. Keep originals available for active sessions and use the right store for the handle type.

See [the Caveman MCP reference](https://docs.caveman.so/docs/mcp) for supported tools and errors.

## Compare one change at a time

Run a direct baseline and a candidate with the same host, model, task, and initial workspace. Test tool discovery, argument correctness, final output, and total usage across the session.

Count failed tool calls, recovery, and retries. Keep skill state fixed if the experiment concerns tool input. Inspect provider usage and cache fields; local schema bytes are a diagnostic measure.

A useful result might be a smaller tool set for one workflow, shorter descriptions with unchanged selection accuracy, or compressed results that preserve the final answer. Adopt the specific change that passes rather than claiming all MCP traffic is waste.

[The coding-agent setup guide](/guides/coding-agent-setup) covers supported launchers. [Cost measurement](/guides/measure-agent-cost) keeps the result tied to accepted work.