headroom MCP Server: Compressing AI Context for LLMs
headroom: Context Compression for MCP Clients
headroom is an MCP Server that drastically reduces the token count of AI agent inputs by compressing tool outputs, logs, files, and RAG chunks before they ever reach an LLM. It can achieve 60-95% fewer tokens while preserving the original answers, a critical capability for managing API costs and context window limits in AI applications.
Core Compression Mechanisms
At its heart, headroom provides several pathways for context compression. For direct integration into Python or TypeScript applications, it offers a compress(messages) library function. Developers can also deploy it as a proxy using headroom proxy --port 8787, enabling zero-code changes for any language communicating with an LLM.
Beyond these, headroom can wrap existing agents like Claude, Codex, Cursor, Aider, and Copilot with a single command, headroom wrap claude|codex|cursor|aider|copilot. This allows for immediate token reduction without deep integration work.
MCP Server Capabilities
As an MCP Server, headroom exposes specific tools for any compliant MCP client. These include:
headroom_compress: For sending raw context to headroom for token reduction.headroom_retrieve: To fetch the original, uncompressed content if needed, leveraging headroom's reversible (CCR) caching.headroom_stats: To query compression metrics or other relevant statistics.
This integration means that an MCP-enabled LLM or agent can offload context management and compression directly to headroom, treating it as a specialized service.
Enhancing Agent Performance and Memory
headroom also includes features that go beyond simple compression. It provides a cross-agent memory store, allowing shared context across different LLMs like Claude, Codex, and Gemini, complete with automatic deduplication. This helps maintain consistent context and reduces redundant data processing.
Another notable feature is headroom learn. This tool mines failed sessions and automatically writes corrections to files like CLAUDE.md or AGENTS.md. This capability allows headroom to adapt and improve its compression and context handling over time based on real-world usage patterns.