How to Reduce MCP Token Usage in Coding Agents

If your coding agent is burning context before it reads your repository, reduce the MCP surface before changing models or buying a larger plan. The practical target is two separate numbers: tokens spent describing tools on each request, and tokens added by each tool result.

This distinction matters because a small result does not make a large tool catalog free. Claude Code, Codex, Cursor, and other hosts differ in when and how they load MCP definitions, so measure the host you actually use. Cutting either category also reduces overall API cost when your provider bills input tokens.

1. Measure the schema baseline

Under the official MCP tools specification, version 2025-06-18, a tools/list response can include each tool’s name, description, input schema, output schema, and annotations. That JSON is useful, but a large catalog can become recurring prompt material.

Measure it in two ways.

First, capture the catalog. The official MCP Inspector documentation says its Tools tab lists available tools and shows their schemas and descriptions. Connect the Inspector to the same server configuration your agent uses and record the tool count. Capture the raw tools/list JSON from your host’s MCP debug log or JSON-RPC trace, following every nextCursor until none remains. Run the combined JSON through the tokenizer for the exact model in production. Tokenization differs by model, so do not treat character count as the final figure.

Second, measure end-to-end overhead in your host:

1. Start a fresh session with MCP disabled and send a fixed prompt such as Reply only with OK.
2. Record the first request’s input-token count from the host or provider usage log.
3. Start another fresh session with MCP enabled, with every other setting unchanged, and repeat the prompt.
4. Subtract the disabled result from the enabled result.
5. Repeat both runs and compare medians to reduce noise from changing wrappers or cached input.

Call the difference MCP startup overhead, not pure schema size: a host may add routing instructions around the schemas. That is still the number that affects your context and bill.

Keep a small measurement table:

Metric	Before	After
Exposed tools	measured count	measured count
tools/list tokens	tokenizer result	tokenizer result
First-request input tokens	median	median
Representative tool-result tokens	median	median

Store the measurements with the server and agent versions so later comparisons remain attributable and reproducible.

2. Load only the tools this repository needs

Disable unused MCP servers first. Then narrow broad servers to task-specific tool groups or individual tools. A repository that only reads issues and pull requests does not need deployment, security-scanning, organization-management, and write tools in every conversation.

The official GitHub MCP Server documentation supports --toolsets and --tools. It says that enabling only needed toolsets can reduce context size, as of 2026-07-20. A minimal local configuration can look like this:

github-mcp-server --tools get_file_contents,issue_read

The exact host configuration varies, so use the host’s documented allow-list or per-server enable controls. Prefer one small default profile and separate profiles for release work, issue triage, and administration. Do not load the union of every profile just because the server offers it.

Restart the host after changing the catalog, then repeat the baseline measurement. Confirm that the removed tools are absent from tools/list; a hidden menu item is not evidence that its schema stopped reaching the model.

3. Filter fields and truncate large results

Tool output can dwarf schema overhead. A real GitHub MCP Server issue opened on 2025-04-06 reported that list_commits returned 30 commits with roughly 5–6 KB per commit. The follow-up model request exceeded 64,000 tokens and requested 68,490 tokens against a 30,000-token-per-minute account limit. The reporter identified unused author, committer, and verification data—including signatures—as removable fields.

Treat upstream API objects as private implementation details. Return only fields the agent will branch on. For a commit list, that might be SHA, subject, author name, timestamp, and URL—not the full nested REST response.

{
  "items": [
    {"sha": "a1b2c3d", "subject": "Fix cache key", "author": "Rae"}
  ],
  "truncated": true,
  "nextCursor": "opaque-value"
}

Add an application-defined row and byte budget, and label it as your policy rather than an MCP protocol limit. When the budget is reached, return truncated: true, a cursor, and a short summary. Apply field projection before serialization; cutting a string after producing a huge JSON object can leave invalid or misleading data.

Also make verbose fields opt-in. Parameters such as include_diff, include_body, or include_verification should default to false when the common task does not need them. Test the worst normal case, not only an empty repository.

4. Return resource links instead of blobs

Do not inline a long log, generated report, database export, or source archive when the agent may not need to read it. The MCP tools specification dated 2025-06-18 allows a tool result to return a resource_link with a URI, name, description, and MIME type. The client can then fetch the resource when needed.

Return a compact result with the decision-relevant summary plus links:

{
  "content": [
    {"type": "text", "text": "Build failed in 2 test files."},
    {
      "type": "resource_link",
      "uri": "buildlog://runs/8421",
      "name": "full-build.log",
      "mimeType": "text/plain"
    }
  ]
}

The official MCP resources specification, version 2025-06-18 defines resources by URI and lets clients retrieve contents with resources/read. This changes a forced large payload into an on-demand read. Verify that your host supports both resource links and resource reads before adopting the pattern. Keep access controls identical to the original tool: a resource link is not permission to expose data more broadly.

5. Verify savings without changing the workload

Re-run the same fresh-session schema test and the same representative tool calls. Keep the host, model, prompt, repository state, result page, and cache state fixed. Record input tokens for the request before the tool call and for the follow-up request containing the result.

Calculate both reductions:

schema reduction = 1 - (after startup overhead / before startup overhead)
result reduction = 1 - (after result tokens / before result tokens)

For an illustrative calculation, reducing measured startup overhead from 18,000 to 6,000 tokens is a 66.7% reduction. Those are example values, not measurements from a named agent. The GitHub issue supplies a real before figure of 68,490 requested tokens but no comparable post-fix token count, so it should not be presented as a measured before-and-after result.

Then run one real coding task and check that the agent still selects the right tool and can request omitted detail through pagination or a resource read. A lower token count is not a win if the agent needs repeated recovery calls.

Finish with a regression budget in your server tests: snapshot the exposed tool count, serialized schema size, and representative response size. Fail review when an accidental field or new tool pushes them above your team’s recorded baseline. Re-measure after server or host upgrades because tool loading behavior can change.

The useful outcome is not the smallest possible MCP server. It is a scoped catalog and bounded responses that preserve the decisions your coding agent needs.