How to Reduce MCP Token Usage in Claude Code and Codex

If Claude Code or Codex burns through context before the real work starts, check the integration surface before blaming the model. A long conversation, oversized file reads, verbose command output, and MCP tool results can all consume tokens. In clients that load tool definitions up front, a large MCP catalog can add another fixed cost.

The practical fix is to measure first, remove unused servers, discover tools only when a task needs them, inspect one selected schema, and keep results bounded. Claude Code now defers MCP tool definitions by default through Tool Search, so its first diagnostic is to confirm that deferral is active. For Codex and other clients, measure the actual session instead of assuming the same behavior.

This guide gives you a reproducible workflow that works across both clients without promising a made-up percentage reduction.

What Actually Uses the Context Window?

An agent session can contain several kinds of input:

• system and project instructions;

• conversation history and previous responses;

• files, images, and other attachments;

• tool names, descriptions, and JSON schemas;

• tool results, terminal output, and error messages.

MCP defines how a client lists tools and receives each tool's description and input schema. It does not require every client to place every schema in the model context at session start. That loading policy belongs to the client.

This distinction matters. Claude Code's current default is Tool Search: tool definitions are deferred, only tool names load initially, and full definitions enter context when Claude selects them. Codex supports local and remote MCP servers, but its public MCP documentation does not make the same tool-deferral guarantee. Treat each host as a system to inspect and measure.

Prerequisites

Before changing anything, prepare:

1. A repeatable task that uses one external integration, such as listing five recent GitHub issues or reading ten PostHog events.

2. The same model and repository for every comparison.

3. A fresh session for each run.

4. A way to view usage. In Claude Code, use /context to inspect context categories and /usage for session usage. In Codex, record the usage information your current client exposes.

5. A list of the MCP servers currently enabled in the client.

If you want an on-demand integration catalog instead of many separate servers, give your agent the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then verify Aident Loadout and its managed connections:

aident account auth status
aident vault vault --action status

Step 1: Establish a Clean Baseline

Start a new session with your normal MCP configuration. Run the repeatable task once and record:

Do not compare a short lookup with a different, open-ended task. A useful test changes one variable at a time.

In Claude Code, also run:

/mcp
/context
/usage

The MCP panel shows configured servers and their tool counts. The context view shows whether MCP tools, project instructions, files, or conversation history are the larger contributor.

Step 2: Confirm Claude Code Tool Search Is Active

Claude Code enables Tool Search by default for supported models and first-party endpoints. It defers full tool definitions until they are needed. If you explicitly disabled it, or use an environment where the fallback loads tools up front, a large catalog can occupy more context.

Check your settings and environment for ENABLE_TOOL_SEARCH. These values have different effects:

• unset or true: defer MCP tools and discover them on demand;

• auto: defer only when definitions exceed 10% of the context window;

• auto:5: use a custom 5% threshold;

• false: load all definitions up front.

For most large tool collections, keep the default. If you need a threshold for a small set, launch a test session with:

ENABLE_TOOL_SEARCH=auto:5 claude

Run /context again. Expected result: MCP definitions should no longer dominate the initial context, while the tools required by the task remain discoverable.

Common failure: Tool Search is unavailable behind a proxy or with a model that does not support the required tool references. In that case, do not force the setting and assume it worked. Restore the supported client configuration or reduce the enabled server set manually.

Step 3: Disable Servers You Do Not Need

Even with discovery, fewer active integrations make routing, permissions, and debugging easier. Disable an unused server for the test instead of deleting its configuration or credentials.

In Claude Code, use /mcp to inspect and disable servers that do not belong to the current job. In Codex, review the MCP entries in your user or project configuration and enable only the servers needed for the test.

Keep a small set always available only when nearly every task needs it. A database migration session probably does not need marketing, CRM, design, and video-generation tools at the same time.

Expected result: the client starts with a smaller relevant surface and still completes the baseline task. If the task fails because a required server is missing, re-enable that server rather than enabling the entire previous collection.

Step 4: Search for One Action Instead of Loading a Catalog

A search-first capability layer keeps the broad catalog outside the agent's immediate tool list. With Aident Loadout, describe the job in plain language:

aident capabilities search \
  --query "list the five most recent open GitHub issues with title, author, and URL" \
  --types '["action"]' \
  --limit 5

Choose the action that matches the verb, object, and output. Then inspect only that action's contract, using the exact action name returned by the search as <selected-action>:

aident capabilities get \
  --name "<selected-action>" \
  --parts '["description","inputSchema","examples"]'

This sequence gives the agent a short search result and one relevant schema instead of asking it to reason over every integration contract.

Expected result: one selected action with required inputs you can validate before execution. If the search is noisy, make the query more specific. “GitHub” is broad; “list five open issues updated this week” expresses an operation and a bounded result.

Step 5: Execute With a Bounded Result

Use the smallest input that can answer the question. Ask for a limit, fields, date window, repository, project, or status when the selected schema supports them:

aident capabilities execute \
  --name "<selected-action>" \
  --input '{"owner":"example","repo":"project","state":"open","limit":5}'

The field names above are illustrative. Use the inspected schema as the contract; do not guess provider arguments.

Large results can cost more context than tool definitions. Prefer:

• five relevant records over every record;

• a seven-day window over all history;

• selected fields over raw provider payloads;

• a summary plus stable links over copied document bodies;

• pagination over one unbounded response.

MCP supports cursor-based pagination for list operations. When a tool returns a cursor, fetch another page only if the first page did not answer the task.

Common failure: the integration ignores a requested limit or returns a verbose nested payload. Stop before repeating the same call. Look for a more specific action, a projection field, or a pagination input.

Step 6: Keep Long Sessions From Hiding the Improvement

Reducing tool overhead will not rescue a session already filled with unrelated work. Repeated file reads, build logs, search results, and old instructions remain part of the comparison.

For Claude Code:

• use /clear when switching to an unrelated task;

• use /compact when the current task must continue with a shorter history;

• move specialized instructions from the always-loaded CLAUDE.md into on-demand Skills;

• stop verbose commands early and rerun a targeted form.

For Codex, start a new task for unrelated work and keep repository instructions concise and durable. In either client, summarize a large result before continuing instead of carrying the entire payload through many turns.

Step 7: Repeat the Same Test

Open another fresh session and run the original task with:

1. only the required MCP servers enabled;

2. tool deferral active where the client supports it;

3. search, one schema inspection, and one bounded execution;

4. the same model, repository, and requested output.

Compare correctness first, then context and usage. A lower token count is not a win if the agent picked the wrong action, omitted required evidence, or needed many retries.

Your result is credible when the task stays correct and repeatable while the initial context, tool-related input, or returned payload decreases. Report the observed numbers from your client. Do not generalize one run into a universal “90% savings” claim.

Troubleshooting Checklist

MCP context is still high in Claude Code

Run /context, confirm ENABLE_TOOL_SEARCH is not false, and check whether your model or proxy supports Tool Search. Also inspect servers or tools marked to always load.

The tool exists but the agent cannot find it

Describe the exact task and use the provider or object name in the search. If a server was just enabled, restart or reload the client so it refreshes the available tools.

Token usage rises after the tool call

The result is probably the problem. Add a limit, date range, field selection, or pagination boundary. Avoid returning full logs, transcripts, issue histories, or binary data in the conversation.

Disabling MCP servers makes no visible difference

The client may already defer definitions, or another context category may be larger. Compare a fresh session and inspect instructions, file reads, command output, and conversation history.

Search adds an extra step

That is an intentional tradeoff. On-demand discovery adds a lookup before first use, but it avoids keeping a broad set of full schemas in the working context. For a tiny tool set used on nearly every turn, always loading those few tools may be simpler.

Why the Fix Works

The pattern is progressive disclosure:

1. Keep a small discovery surface available.

2. Load the full contract only for a selected action.

3. Send the minimum valid input.

4. Return only the evidence needed for the next decision.

This preserves context for the repository, the user's goal, and the agent's reasoning. It also makes failures easier to diagnose because discovery, schema validation, execution, and result size are separate steps.

The lesson from Aident's highest-traffic technical guide is structural, not topical: readers respond to a specific problem, a direct answer, reproducible steps, expected results, and exact failure modes. Use the same discipline when measuring your agent. The result should be a repeatable before-and-after test, not a slogan about token savings.

Ready to replace a long static integration list with search-first discovery? Connect one integration with Aident Loadout, run the baseline above, and compare the same task in a fresh session.

Sources

• Claude Code: connect to tools via MCP and configure Tool Search

• Claude Code: manage costs and reduce token usage

• Claude Code: inspect the context window

• OpenAI Codex: Model Context Protocol

• Model Context Protocol tools specification

• Model Context Protocol pagination specification

• Anthropic: code execution with MCP

• Aident Loadout setup

• Aident: Agent Skills vs MCP vs CLI

• Aident: MCP vs API