HeadroomMCP Server

What it does

Headroom attacks the most wasteful part of an agent loop: the raw text an agent reads. Tool responses, database rows, log tails, file reads and RAG chunks are mostly boilerplate the model never needs, and every one of those tokens is paid for on each turn. Headroom compresses that payload before it reaches the model, and the project reports 60-95% fewer tokens on JSON and roughly 20% fewer across a typical coding-agent session, with answers unchanged.

As an MCP server it exposes three tools to any MCP-compatible host:

• headroom_compress — compress content on demand, returning a hash key plus the token savings it measured
• headroom_retrieve — recover the original, uncompressed content from that hash key
• headroom_stats — session totals for tokens saved and estimated cost saved

Why the retrieve step matters

Most context trimming is lossy and irreversible: once a summariser has thrown away a stack trace, the agent cannot get it back. Headroom's compression is reversible through a compress-cache-retrieve store, so the model sees a compact form by default and can pull the full original when it actually needs the detail. Compression is content-type aware — JSON arrays, source code, logs, git diffs and prose each get a different strategy — and error preservation uses field-variance statistics to keep anomalies and out-of-range values rather than a fixed keyword list.

Deployment

The MCP server is one of four ways to run it; Headroom also ships as a transparent proxy that needs no code changes, a Python function, a TypeScript function, and adapters for LangChain, Agno, Strands, LiteLLM and the Vercel AI SDK. Running the proxy alongside the MCP server compresses all traffic automatically instead of only what the agent explicitly compresses.

Practical notes

Apache 2.0, from Headroom Labs (founded by former Netflix engineer Tejas Chopra). The CLI is published as headroom-ai on both PyPI and npm; uv tool install "headroom-ai[mcp]" is the recommended install so the binary lands on PATH. Some clients need the absolute path from command -v headroom rather than the bare command. The full [all] extra pins to Python 3.13 because one dependency will not build on 3.14+, though token savings still track correctly on 3.14.