Shrink big tool outputs before your agent reads them with Headroom MCP
Headroom MCP gives Claude, Cursor and other agents three tools to compress large tool outputs, logs and JSON locally and fetch the original back when needed. Setup and what I saw testing version 0.44.0.
A lot of what fills an agent's context window is not your question or its reasoning. It is tool output: a search result with fifty near identical rows, a log dump, a JSON response that repeats the same keys hundreds of times. Headroom is an open source project that compresses that kind of content before the model reads it, and keeps the original on your machine so nothing is lost.
Headroom is a bigger tool than its MCP server. It also ships a Python and TypeScript library, a local proxy and a wrapper that sits in front of Claude Code, Codex, Cursor and others. This post covers the MCP server, because it is the lightest way to try it with any MCP client and it does not reroute your model traffic. The repo is Apache 2.0, close to 80,000 stars when I checked today, and version 0.44.0 went out on November 10. I ran that version locally before writing this.
The three tools
- headroom_compress takes a block of content and returns a smaller version, a hash, and the token counts before and after.
- headroom_retrieve takes that hash and returns the original, untouched.
- headroom_stats shows what was compressed in the session and how many tokens it saved.
