Bug: /context command over-reports MCP server token usage by ~3x

Summary

The /context command significantly inflates reported token usage for MCP servers. Testing with a 60-tool MCP server for example XcodeBuildMCP shows ~45,000 tokens reported, but actual consumption measured via the count_tokens API is ~15,000 tokens, a threefold overstatement.

Root Cause Hypothesis

The discrepancy appears to stem from how Claude Code calculates token usage. It seems to query Anthropic's count_tokens API individually for each tool, then sum those results. This methodology inadvertently counts shared system instructions and wrapper formatting once per tool rather than once per complete request.

Anthropic automatically injects system guidance for tool use into requests. According to the platform documentation:

"When you use tools, we also automatically include a special system prompt for the model which enables tool use."

For Claude Sonnet 4.5, this hidden prompt costs approximately 313–346 tokens per count_tokens call.

Measurement Data

| Measurement Method | Tokens |
|---|---|
| Direct measurement of tool JSON | 14,081 |
| Single batched count_tokens API call | 15,282 |
| /context command (60 individual tool queries summed) | 45,018 |
| Discrepancy | ~30,937 |

Minimal Reproduction

A minimal experiment with two identical echo tools demonstrates the problem:

| Method | Tokens |
|---|---|
| Counted together | 672 |
| Counted separately and summed | ~1,167 |
| Per-tool overhead | ~247 |

With 60 tools, this overhead (~300 tokens × 60) accounts for the ~18,000-20,000 token discrepancy.

Expected Behavior

The /context command should report actual token consumption as experienced by the API—i.e., calling count_tokens once with all MCP tools batched together, not summing individual per-tool queries.

Impact

• Users see grossly inflated token consumption figures
• Users may disable useful MCP servers based on misleading numbers
• Context budget planning becomes unreliable
• Reported numbers misrepresent actual API costs

Environment

• Claude Code: Latest version (tested January 2025)
• MCP Server: XcodeBuildMCP with 60 tools
• Platform: macOS

References

• Blog post with detailed investigation: https://www.async-let.com/posts/claude-code-mcp-token-reporting.md