`wiki/` **is not published anywhere.** `.github/workflows/docs.yml` says so in its own header, no mkdocs or sphinx config exists, and `wiki/**` sits in `paths-ignore` for CI — changes there don't even run a build. It survives as pending-migration reference material for contributors. That's why this is separate from the published-site work in #3388: nothing here reaches a user through `docs.headroomlabs.ai`. It still matters, because a contributor migrating a page would carry its errors across, and because the repo is public. ## The finding that justifies this PR on its own `wiki/benchmarks.md` carried an entire **invented "Production Telemetry" section**, presented as real-world fleet data: > real-world production telemetry from 250+ active proxy instances … **52ms median overhead** … **1.4 billion tokens saved** across 249 instances Plus P90/P99 timings, ~$4,000 saved, an OS split, a version-share breakdown, and a dated collection window of March 30 – April 2, 2026. A repo-wide grep for those figures **matches only that one file.** No script, test or fixture produces them. The published benchmarks page never carried the section, so the site owner had already excised it. Removed rather than re-estimated. The per-category ranges hanging off it (4.8%, 40–80%, 83–94%, 85–94%, 60–76%) went with it and now point at the concrete compression table on the same page. The same page also described `HEADROOM_TELEMETRY` as the opt-in switch governing fleet-wide numbers. Fleet data would come from `HEADROOM_BEACON` — a **separate switch that defaults ON**. That note is gone with the section it footnoted; the accurate description of both switches shipped to the live site in #3388. ## Other corrections, each verified against source - **`wiki/agno.md`** constructed `HeadroomAgnoModel(config=...)`; the field is `headroom_config` (`integrations/agno/model.py:135`). The sibling `HeadroomPreHook` genuinely does take `config`, which is how they got conflated. - **`wiki/ccr.md`** documented CLI flags that don't exist, and a dead demo script. - **`wiki/image-compression.md`** had two broken CLI examples. - **`wiki/getting-started.md`** used `plan.transforms_applied`; `SimulationResult` exposes `transforms`. (`CompressResult` really does have `transforms_applied` — two different result types, easy to cross.) - **`wiki/cli.md`** documents 15 of ~27 top-level commands; an audit note now says so rather than implying completeness. ## Disposition, for whoever picks up the migration `wiki/cli.md` is the highest-value page to port — no site page is a full CLI reference, and `docs.yml` names it as the reason `wiki/` still exists. `wiki/integration-guide.md` and `wiki/configuration.md` also cover ground the site doesn't. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
7.2 KiB
MCP Server — Context Engineering Toolkit
Headroom's MCP server exposes compression, retrieval, and observability as tools that any MCP-compatible AI coding tool can use — Claude Code, Cursor, Codex, and more.
Quick Start
# Install (MCP is included with proxy, or standalone)
pip install "headroom-ai[proxy]" # Proxy + MCP tools
pip install "headroom-ai[mcp]" # MCP tools only (lightweight)
# Register with Claude Code (one-time)
headroom mcp install
# Start Claude Code — it now has headroom tools!
claude
That's it. Claude Code can now compress content on demand, retrieve originals, and check session stats — no proxy required.
For automatic compression of ALL traffic, also run the proxy:
# Terminal 1
headroom proxy
# Terminal 2
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude
Tools
The MCP server provides three tools:
headroom_compress
Compress content on demand. The LLM calls this when it wants to shrink large content before reasoning over it.
Tool: headroom_compress
Parameters:
- content (required): Text to compress (files, JSON, logs, search results, etc.)
Returns:
- compressed: Compressed text
- hash: Key for retrieving the original later
- original_tokens / compressed_tokens / savings_percent
- transforms: Which compression algorithms were applied
Example — Claude reads a large file, then compresses it:
Claude: Let me compress this large output to save context space.
→ headroom_compress(content="[5000 lines of grep results...]")
← {
"compressed": "[key matches with context...]",
"hash": "a1b2c3d4e5f6...",
"original_tokens": 12000,
"compressed_tokens": 3200,
"savings_percent": 73.3,
"transforms": ["router:search:0.27"]
}
The original is stored locally for the session (1-hour TTL). If Claude needs the full content later, it calls headroom_retrieve.
headroom_retrieve
Retrieve original uncompressed content by hash.
Tool: headroom_retrieve
Parameters:
- hash (required): Hash key from compression
- query (optional): Search within the original to return only matching items
Returns:
- original_content (full retrieval) or results (search)
- source: "local" or "proxy"
Retrieval checks the local store first (content compressed via headroom_compress), then falls back to the proxy's store (content compressed automatically by the proxy). Hashes from either source work transparently.
headroom_stats
Session compression statistics — including sub-agent stats and proxy cache info.
Tool: headroom_stats
Returns:
- compressions, retrievals, tokens_saved, savings_percent
- estimated_cost_saved_usd
- recent_events (last 10 compression/retrieval events)
- sub_agents (stats from sub-agent MCP instances, if any)
- combined (main + sub-agent totals)
- proxy (request count, cache hits, cost saved — if proxy is running)
Sub-agent stats are aggregated via a shared stats file at
${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl (default
~/.headroom/session_stats.jsonl — see the
Filesystem Contract). Each MCP server instance
(main session and sub-agents) writes events there, and headroom_stats
reads across all of them.
Architecture
MCP Only (no proxy)
┌─────────────────────────────────────────────┐
│ Claude Code / Cursor / Codex │
│ │
│ LLM calls headroom_compress on demand │
│ ↓ │
│ Compression happens locally in MCP process │
│ Original stored in local CompressionStore │
│ ↓ │
│ LLM calls headroom_retrieve when needed │
└─────────────────────────────────────────────┘
MCP + Proxy (full setup)
┌─────────────────────────────────────────────┐
│ Claude Code │
│ │
│ 1. Sends request ──→ Proxy (auto-compress) │
│ 2. Gets response with compressed outputs │
│ 3. Can call headroom_compress for more │
│ 4. headroom_retrieve checks: │
│ local store → proxy store │
└──────────────────┬──────────────────────────┘
│ MCP (stdio)
▼
┌─────────────────────────────────────────────┐
│ Headroom MCP Server │
│ ├── headroom_compress (local compression) │
│ ├── headroom_retrieve (local + proxy) │
│ └── headroom_stats (aggregated stats) │
└─────────────────────────────────────────────┘
No double-compression: the proxy compresses at the HTTP level (before the LLM sees content). MCP tools operate after the LLM receives content. They don't touch the same data.
CLI Commands
Install
headroom mcp install # Default setup
headroom mcp install --proxy-url http://host:9000 # Custom proxy URL
headroom mcp install --force # Overwrite existing
Status
headroom mcp status
Headroom MCP Status
========================================
MCP SDK: ✓ Installed
Claude Config: ✓ Configured
/Users/you/.claude/mcp.json
Proxy URL: http://127.0.0.1:8787
Proxy Status: ✓ Running at http://127.0.0.1:8787
Uninstall
headroom mcp uninstall
Debug
headroom mcp serve --debug
Cross-Tool Compatibility
The MCP server works with any MCP-compatible host:
| Tool | MCP Support | Setup |
|---|---|---|
| Claude Code | Native | headroom mcp install |
| Cursor | Supported | Add to Cursor MCP settings |
| Codex | If supported | Configure MCP server |
| Any MCP host | Yes | Point to headroom mcp serve |
Troubleshooting
"MCP SDK not installed"
pip install "headroom-ai[mcp]"
"Proxy not running" (when using proxy features)
headroom proxy # In another terminal
"Entry not found or expired"
- Content compressed via
headroom_compress: stored for 1 hour (session TTL) - Content compressed by the proxy: stored for 30 minutes by default (proxy CCR TTL,
HEADROOM_CCR_TTL_SECONDS) - The proxy must be running for proxy-compressed content
Claude doesn't see headroom tools
- Check:
headroom mcp status - Restart Claude Code after installing MCP
- Verify with
/mcpin Claude Code — should show 3 headroom tools
Sub-agent stats not showing
Sub-agent stats appear in headroom_stats only after sub-agents have run compressions. The shared stats file is at ${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl (defaults to ~/.headroom/session_stats.jsonl).