Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

docs: explain Claude MCP usage attribution

oxura10da89d3cee5
diff --git a/docs/content/docs/mcp.mdx b/docs/content/docs/mcp.mdx
index 0ba68d006..9b8fd2eca 100644
--- a/docs/content/docs/mcp.mdx
+++ b/docs/content/docs/mcp.mdx
@@ -184,3 +184,30 @@ The proxy compresses all traffic at the HTTP level (before the LLM sees content)
**"Entry not found or expired"** -- Local content expires after 1 hour, proxy content after 5 minutes.
**Claude doesn't see headroom tools** -- Run `headroom mcp status`, restart Claude Code, and verify with `/mcp` inside Claude Code.
+
+### Claude Code `/usage` attributes a large share to `headroom` MCP
+
+Claude Code counts MCP tool calls and MCP tool results as session context. If a
+long-running workflow or a subagent-heavy command calls `headroom_compress`,
+`headroom_retrieve`, or `headroom_stats` many times, `/usage` can show a visible
+share under the `headroom` MCP server even when Headroom is saving tokens inside
+individual tool results.
+
+That number is not a direct "Headroom overhead" bill. It means Claude Code kept
+Headroom MCP interactions in the conversation context. Deep research workflows
+can amplify this because each subagent has its own requests and may keep its own
+MCP results in context.
+
+Use these checks when the MCP share looks high:
+
+- Run `headroom_stats` and compare `tokens_saved` with the number of MCP calls.
+- Use `/compact` after large MCP-backed investigation steps so old MCP tool
+ results stop occupying the active context window.
+- Prefer the proxy path for automatic compression of normal Claude Code traffic:
+ `headroom proxy` plus `ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude`.
+- Disable the MCP server for sessions where you only want proxy-level
+ compression and do not need on-demand `headroom_compress` or
+ `headroom_retrieve`.
+- For deep research or custom subagent workflows, reduce unnecessary subagent
+ fan-out first; subagent traffic usually dominates the usage picture before
+ MCP overhead does.