# headroom MCP Server: 95% Token Compression for LLMs

> headroom is an MCP Server that dramatically compresses tool outputs, logs, files, and RAG chunks before they reach the LLM, achieving 60-95% token reduction. Developers working with LLMs who need to optimize context window usage will find its MCP capabilities useful.

**Published:** 2026-08-08T12:00:22.023+00:00

**Keywords:** headroom,mcp-server,chopratejasheadroom,token-compression

# 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.

## References
- [headroom on GitHub](https://github.com/chopratejas/headroom)
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/introduction)
- [headroom on model-context-protocol.com](https://model-context-protocol.com/servers/)

## Related Repository

- [headroom](https://model-context-protocol.com/servers/headroom)

**Source:** https://model-context-protocol.com/blog/headroom-mcp-server-95-token-compression-for-llms-mcp-server-guide