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

> Install Headroom's MCP server easily with pip install to enable compression, retrieval, and stats tools for AI assistants like Claude Code and Cursor. Integrate effortlessly and boost your coding workflow.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-20

---

**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):

```bash
pip install "headroom-ai[proxy]"

```

Install MCP tools only (no proxy):

```bash
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](https://github.com/chopratejas/headroom/blob/main/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](https://github.com/chopratejas/headroom/blob/main/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:

```bash
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:

```bash
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:

```bash
headroom proxy

```

Then configure your AI client to use the proxy:

```bash
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:

```python
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](https://github.com/chopratejas/headroom/blob/main/headroom/cli/mcp.py)** module provides the entry points for these operations, while the full tool specifications are documented in **[wiki/mcp.md](https://github.com/chopratejas/headroom/blob/main/wiki/mcp.md)**.

## Monitoring and Management

Check the current installation status and proxy connectivity:

```bash
headroom mcp status

```

Typical output includes:
- MCP SDK installation status
- Claude configuration path
- Proxy URL and reachability

To remove the MCP integration:

```bash
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](https://github.com/chopratejas/headroom/blob/main/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](https://github.com/chopratejas/headroom/blob/main/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](https://github.com/chopratejas/headroom/blob/main/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.