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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
docs: explain Claude MCP usage attribution
oxura10da89d3cee5
diff --git a/docs/content/docs/mcp.mdx b/docs/content/docs/mcp.mdxindex 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.