headroom MCP Server: 95% Token Compression for LLMs
headroom MCP Server: 95% Token Compression for LLMs
headroom is an MCP Server designed to compress various inputs—tool outputs, logs, files, and RAG chunks—before they are processed by an LLM, aiming for 60-95% fewer tokens while maintaining answer quality. This capability is exposed through its MCP server for integration with any MCP client.
MCP Server Capabilities
As an MCP Server, headroom exposes three distinct capabilities: headroom_compress, headroom_retrieve, and headroom_stats. These allow any MCP client to interact with headroom for token compression, original content retrieval, and usage statistics, respectively. This enables developers to integrate headroom's core functionality directly into their MCP-enabled workflows without requiring changes to their existing LLM interaction code.
Compression and Agent Integration
Beyond its MCP server role, headroom offers several integration points. Developers can use it as a Python or TypeScript library via compress(messages) for inline compression within their applications. For zero-code changes, the headroom proxy --port 8787 command sets up a proxy that can be used with any language.
headroom also provides direct agent wrapping with headroom wrap claude|codex|cursor|aider|copilot, allowing it to manage context for specific agents. This includes a cross-agent memory feature that maintains a shared store across Claude, Codex, and Gemini, complete with automatic deduplication.
Reversible Compression and Learning
A key feature of headroom is its Reversible (CCR) capability, which caches original content. This allows for on-demand retrieval of the uncompressed data, ensuring that no information is permanently lost during the compression process.
Additionally, headroom includes a headroom learn command. This tool mines failed sessions and generates corrections, writing them to files such as CLAUDE.md or AGENTS.md. This provides a feedback loop to refine agent interactions and improve future performance.