Headroom vs ref-tools-mcp
Headroom: Headroom compresses context locally through Python entry points and optional MCP or proxy integrations. Our fixed-release tests found content-dependent savings, exact selected JSON round trips, conservative lossless fallback and storage-dependent original retrieval.; ref-tools-mcp: Ref MCP is a server that enables AI coding tools and agents to access technical documentation efficiently. It optimizes token usage by filtering search results and extracting only the most relevant parts of documentation pages, helping models stay focused and reducing operational costs.
Ref trims documentation it fetches from its hosted index. Headroom processes supplied content locally; this review tested logs and structured tool results.
TL;DR
- Your actual serialized tool output contains repetitive logs or uniform arrays, and you can compare both compression modes against minified baselines.
- You can retain originals in an appropriate backend, inspect application-level errors and verify the data needed by your task.
- You require demonstrated answer equivalence or a guaranteed billing reduction; this offline review measured neither.
- Your payloads are already compact heterogeneous JSON, or you require permanent recovery from an in-memory session; our controls exposed limits in those cases.
- Context size is your main concern: page reads return about the most relevant 5k tokens, and repeat searches do not return the same results in a session.
- You want two simple tools, search and read-URL, in Claude Code, Cursor or another MCP client.
- You want to search private resources such as repos and PDFs alongside public docs.
- You cannot send queries to a vendor: it needs an API key and the hosted ref.tools service.
- You want the recommended HTTP server: this repository is the legacy stdio server.
- You need independent proof of the token savings: the README's numbers are the project's own example traces.
Side-by-Side Comparison
Features
Use Cases
Best For
FAQ
Deploy on DigitalOcean
Host your MCP servers, Docker containers, and AI agents with $200 free credit over 60 days.