Claude Code MCP token usage and CLAUDE.md size

Where Claude Code's fixed token overhead comes from

Before your first message the request already holds all of this, and every request re-sends it. The last three are yours, and they only grow.

Measure MCP and CLAUDE.md tokens with /context

1. 1
   Fresh session, then /context

   Everything except messages is fixed overhead: system prompt, system tools, MCP tools, memory files.

2. 2
   Run /mcp

   A server with dozens of long-described tools is usually the biggest single item.

3. 3
   Read the MCP tools line

   A large share before any work is room you lose later, and it brings auto-compact closer.

Why tool definition tokens matter more than they look

Caching makes a fixed block cheaper, not free, and cached tokens still count toward plan limits. See prompt caching vs context compression.

• Paid on every turn, hundreds of times a session.
• Less room for real work. Every definition token is one not available for files and history.
• More ways to choose wrong. A hundred tools is a hundred chances to pick the wrong one.
• Changing them mid-session is a cache miss. They sit near the top of the prefix.

How to cut MCP server overhead

1. 1
   Disconnect what you do not use

   Go through /mcp. Unused for a week means not loaded on every request.

2. 2
   Scope servers per project

   claude mcp add --scope project keeps a server in the repo’s .mcp.json, not everywhere.

3. 3
   Prefer a CLI when one exists

   If the agent can run gh, kubectl or psql, the MCP server adds definitions, not capability.

4. 4
   Pick lean servers

   Enable a subset of tools where you can. Fewer, shorter descriptions cost less.

5. 5
   Set up before you start

   Decide on servers before a long session to avoid the cache miss.

How to keep CLAUDE.md lean

CLAUDE.md is for rules that must hold every turn, which is why it is expensive. The same applies to AGENTS.md in Codex.

• Directory rules go in a CLAUDE.md in that directory, loaded only when Claude works there.
• @ imports still load the file, so they organize but do not save tokens.
• Reference material belongs in a file read on demand or a skill, which loads in full only when used. More in context engineering for coding agents.

A five-minute overhead audit

1. 1
   Take a baseline

   Fresh session, /context. Note MCP tools and memory files.

2. 2
   List servers

   /mcp. Disable any you did not use on this project last week.

3. 3
   Read CLAUDE.md as the agent would

   If a line would not change its behavior, delete it or move it to a file it can open.

4. 4
   Re-measure

   Another fresh session, /context. The difference is room back on every turn.

5. 5
   Share it

   Commit .mcp.json and CLAUDE.md, and repeat when someone adds a server.

What compression can and cannot do about it

Fixed overhead is your job to trim. condense saves on the part that grows; a real 938-turn session came in 72.3% under baseline in the anatomy of a token bill.

Trim first, then run dense claude so the session stays small as it grows. dense info shows context sent against forwarded.

Frequently asked questions