Skip to content
BSWEN
Blog

How to Use Headroom MCP Tools with Claude Code and Cursor

Cowrie
Cowrie
Dev @ Bswen

Problem

I wanted compression inside Claude Code, but I did not want to run a proxy or change base URLs. I needed the LLM itself to decide when to compress — for example, before reasoning over 5,000 lines of grep output. The proxy compresses everything at the HTTP level, which is great for API calls but does not help when the LLM receives content through other channels.

What Are MCP Tools?

Headroom exposes three MCP tools that any MCP-compatible host can call:

  • headroom_compress — compress large outputs on demand
  • headroom_retrieve — retrieve originals by hash
  • headroom_stats — return session stats including estimated cost saved

MCP mode is lightweight. No proxy required. The LLM has agency over compression.

One-Command Setup for Claude Code

Install MCP for Claude Code
headroom mcp install

This registers Headroom with Claude Code automatically. Check status with:

Check MCP status
headroom mcp status

Manual Host Configuration

For Cursor or other MCP hosts, add this to your MCP settings:

mcp_config.json
{
  "mcpServers": {
    "headroom": {
      "type": "stdio",
      "command": "headroom",
      "args": ["mcp", "serve", "--proxy-url", "http://127.0.0.1:8787"]
    }
  }
}

You can also start in debug mode to see what is happening:

Debug MCP server
headroom mcp serve --debug

How the LLM Uses Them

When Claude Code gets a large tool output, it can call:

LLM tool call flow
large output (5000 lines)
       |
       v
   headroom_compress
       |
       +---> compressed text + hash
       |
   LLM reasons over compressed version
       |
   Needs more detail?
       |
       v
   headroom_retrieve(hash=abc123, query="auth middleware")
       |
       +---> original lines matching query

The LLM decides when compression helps and when retrieval is needed.

What headroom_compress Returns

compress response
{
  "compressed_text": "...",
  "hash": "abc123",
  "original_tokens": 5000,
  "compressed_tokens": 500,
  "transforms_applied": ["smartcrusher", "dedup"]
}

Stats and Cost Tracking

headroom_stats returns session stats including estimated cost saved in USD. Sub-agent stats are aggregated via a shared stats file.

Important Limitations

Local entries expire after 1 hour for MCP-only mode, or 5 minutes for proxy-backed mode. Long-running sessions may need proxy-backed retrieval for data that outlives the cache TTL.

Also, MCP tools do not double-compress proxy traffic. They handle different data and do not conflict.

Summary

In this post, I showed how to set up Headroom MCP tools for Claude Code and Cursor. The key point is that MCP mode gives the LLM control over compression, letting it compress large outputs on demand and retrieve originals when needed — all without running a proxy.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: