How to Set Up and Install Headroom's MCP Server for Compression, Retrieval, and Stats Tools

Headroom's MCP server is a stdio-based Model Context Protocol implementation that exposes headroom_compress, headroom_retrieve, and headroom_stats tools to AI coding assistants, requiring only a pip install and single registration command to integrate with Claude Code or Cursor.

The chopratejas/headroom repository provides a lightweight MCP server that brings on-demand text compression and retrieval capabilities directly into your AI workflow. By installing the optional MCP dependencies, you can register the server with compatible clients and immediately start compressing large contexts to reduce token usage. This guide walks you through the complete setup and installation process, from package installation to tool invocation.

Prerequisites and Installation

Installing the Package

Headroom distributes the MCP server as an optional extra. You can install it alongside the proxy for full functionality or as a standalone lightweight client.

Install with proxy support (recommended):

pip install "headroom-ai[proxy]"

Install MCP tools only (no proxy):

pip install "headroom-ai[mcp]"

Both commands automatically pull in the mcp SDK and register the headroom CLI entry points. The [proxy] extra includes the HTTP interception layer, while [mcp] provides only the stdio server and tool definitions.

Architecture Overview

The server implementation lives in headroom/ccr/mcp_server.py. It instantiates a HeadroomMCPServer class that registers three tools with the MCP SDK:

• headroom_compress – Accepts large text content, compresses it using Headroom's pipeline (headroom.compress.compress), stores the original in a shared CompressionStore, and returns a hash key.
• headroom_retrieve – Looks up content by hash in the local store. If not found and a proxy URL is configured, it transparently forwards the request to the proxy's /v1/retrieve endpoint.
• headroom_stats – Aggregates session-wide metrics (compression count, token savings, estimated cost) from a JSON-line shared file (session_stats.jsonl).

Original content is cached with a 1-hour TTL (MCP_SESSION_TTL) via the headroom/cache/compression_store.py module. The server uses stdio for transport, making it compatible with any MCP client that launches subprocesses.

Registering and Running the Server

One-Time Registration

Register the server with your AI client using the CLI. For Claude Code, this creates ~/.claude/mcp.json automatically:

headroom mcp install

This command writes the configuration pointing to headroom mcp serve as the server executable. You only need to run this once per machine.

Starting the Server

Launch the stdio server in its own terminal:

headroom mcp serve

You will see initialization logs indicating the proxy URL (default http://127.0.0.1:8787) and tool registration status. The server remains running and handles JSON-RPC requests from the client until terminated.

Proxy Integration (Optional)

To enable automatic HTTP-level compression alongside the MCP tools, run the Headroom proxy in a separate terminal:

headroom proxy

Then configure your AI client to use the proxy:

ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

When the proxy is active, headroom_retrieve will fall back to the proxy’s compression store if the local cache misses, ensuring seamless retrieval regardless of which component performed the original compression.

Using the MCP Tools

Once the server is running, your AI assistant can invoke the tools directly. The client calls are handled automatically, but the following Python snippet demonstrates the underlying SDK interaction:

from mcp.client import Client

client = Client()

# Compress a large context

result = client.call_tool("headroom_compress", {
    "content": "Very large text content..."
})
hash_key = result["hash"]

# Retrieve later

original = client.call_tool("headroom_retrieve", {
    "hash": hash_key
})

# Check statistics

stats = client.call_tool("headroom_stats", {})
print(f"Saved {stats['tokens_saved']} tokens")

The headroom/cli/mcp.py module provides the entry points for these operations, while the full tool specifications are documented in wiki/mcp.md.

Monitoring and Management

Check the current installation status and proxy connectivity:

headroom mcp status

Typical output includes:

• MCP SDK installation status
• Claude configuration path
• Proxy URL and reachability

To remove the MCP integration:

headroom mcp uninstall

This deletes the configuration file from the client’s config directory without affecting the installed Python package.

Summary

• Install via pip install "headroom-ai[proxy]" to get the MCP server and optional proxy.
• Register once with headroom mcp install to configure Claude Code or Cursor.
• Serve the tools by running headroom mcp serve in a dedicated terminal.
• Integrate optionally with headroom proxy for automatic HTTP compression and seamless retrieval.
• Manage installation using headroom mcp status and headroom mcp uninstall.

Frequently Asked Questions

What is the Model Context Protocol (MCP)?

The Model Context Protocol is an open standard that allows AI coding assistants to communicate with external tools via a standardized JSON-RPC interface over stdio. Headroom implements this in headroom/ccr/mcp_server.py to expose compression and retrieval capabilities as native tools that Claude Code or Cursor can invoke automatically when context limits are reached.

Do I need to run the Headroom proxy to use the MCP server?

No. The MCP server runs independently and maintains its own in-memory compression store. However, running the proxy alongside the server (as described in wiki/mcp.md) enables automatic compression of HTTP traffic and allows the MCP headroom_retrieve tool to fetch content that was compressed by the proxy, providing a unified caching layer.

Where is compressed data stored when using the MCP tools?

Compressed data is stored in the CompressionStore defined in headroom/cache/compression_store.py. By default, this is an in-memory store with a 1-hour TTL. If you run the proxy, it maintains its own persistent store, and the MCP server will fall back to querying it when local retrieval fails.

How do I remove the MCP integration from Claude Code?

Run headroom mcp uninstall from your terminal. This command removes the configuration entry from ~/.claude/mcp.json (or the equivalent config directory for your client) without uninstalling the Python package. To completely remove the software, run pip uninstall headroom-ai after uninstalling the MCP configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}