# How to Use Headroom MCP Server for Tool Retrieval: Complete Setup Guide

> Learn to use the Headroom MCP server for efficient tool retrieval. This guide covers setup and explains how headroom_compress and headroom_retrieve work with stdio for content management.

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

---

**The Headroom MCP server exposes `headroom_compress`, `headroom_retrieve`, and `headroom_stats` tools via stdio, enabling any MCP-compatible host to compress content, store it by hash, and retrieve it from either a local CompressionStore or a fallback proxy.**

The Headroom MCP server from the `chopratejas/headroom` repository is a lightweight, stdio-based Model Context Protocol implementation designed for AI coding assistants like Claude Code, Cursor, and Codex. This guide explains how to configure the server, use the retrieval pipeline, and understand the underlying architecture that powers `headroom_retrieve`.

## What the Headroom MCP Server Does

The `HeadroomMCPServer` class defined in [`headroom/ccr/mcp_server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/mcp_server.py) (lines 8-15) orchestrates three MCP tools: `headroom_compress`, `headroom_retrieve`, and `headroom_stats`. When running stand-alone, the server stores compressed content in a local `CompressionStore` and serves retrieval requests from that store. When a Headroom proxy is available at `http://127.0.0.1:8787`, the server automatically falls back to the proxy’s compression store for hashes not found locally, creating a dual-mode architecture that works whether you run the full proxy (`headroom proxy`) or only the lightweight MCP server (`headroom mcp serve`).

Key components include:

- `create_ccr_mcp_server` factory (lines 886-898): Public entry point for CLI and programmatic use
- `_compress_content` (lines 55-84): Runs compression, stores originals, returns hash
- `_retrieve_content` (lines 10-38): Handles local lookup and optional proxy fallback via `GET /v1/retrieve`
- Session stats: Appends to `${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl` for cross-process aggregation

## Installation and Registration

Install the package using pip. Choose the lightweight option if you only need MCP tools, or the proxy option if you want HTTP-level compression support.

```bash
pip install "headroom-ai[mcp]"      # lightweight, no proxy

# OR

pip install "headroom-ai[proxy]"    # includes proxy + MCP tools

```

Register the server with Claude Code to enable automatic startup:

```bash
headroom mcp install

```

This command writes a TOML block `[mcp_servers.headroom]` to `~/.claude/mcp.json` pointing to `headroom mcp serve` (as verified in [`tests/test_mcp_registry/test_codex_registrar.py`](https://github.com/chopratejas/headroom/blob/main/tests/test_mcp_registry/test_codex_registrar.py), lines 86-120).

## Starting the Server

You can start the server manually for debugging or allow Claude Code to launch it automatically.

To run manually with debug logging:

```bash
headroom mcp serve --debug

```

The `serve` sub-command in [`headroom/cli/mcp.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/mcp.py) (lines 330-352) creates a `HeadroomMCPServer` via `create_ccr_mcp_server` and invokes `run_stdio()` to begin the stdio transport loop.

For programmatic usage in Python:

```python
from headroom.ccr.mcp_server import create_ccr_mcp_server

mcp_server = create_ccr_mcp_server(proxy_url="http://127.0.0.1:8787")
await mcp_server.run_stdio()

```

## Optional Proxy Integration

For automatic HTTP-level compression and shared storage across multiple sessions, run the Headroom proxy in a separate terminal:

```bash
headroom proxy

```

When the proxy is reachable at `http://127.0.0.1:8787`, the MCP server queries it via `_retrieve_via_proxy` whenever the local `CompressionStore` misses a hash lookup.

## How Retrieval Works Under the Hood

The retrieval pipeline follows a strict sequence defined in `_handle_retrieve` (lines 443-468):

1. **Local lookup**: The server checks its `CompressionStore` (initialized lazily in `_get_local_store`) which maintains `original → compressed` pairs with a TTL of `MCP_SESSION_TTL = 3600` seconds.

2. **Proxy fallback**: If `check_proxy=True` (the default) and `httpx` is available, the server POSTs to `/v1/retrieve` on the proxy when the local store misses.

3. **Event logging**: Each compression or retrieval appends a JSON line to the shared stats file, enabling `headroom_stats` to aggregate data across sub-agents and processes.

## Code Examples

Check the server configuration and health status:

```bash
headroom mcp status

```

This reports SDK availability, Claude config path, proxy URL, and proxy health (sourced from [`headroom/cli/mcp.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/mcp.py), lines 164-168).

Use the retrieval tool from an MCP client:

```python
import json
import asyncio
from mcp.client import Client

async def retrieve(hash_key: str):
    async with Client("headroom") as client:
        result = await client.call_tool(
            "headroom_retrieve",
            {"hash": hash_key}
        )
        print(json.dumps(result, indent=2))

asyncio.run(retrieve("a1b2c3d4e5f6"))

```

## Summary

- The Headroom MCP server provides `headroom_compress`, `headroom_retrieve`, and `headroom_stats` via stdio for any MCP-compatible host.
- Install with `pip install "headroom-ai[mcp]"` and register using `headroom mcp install`.
- The server automatically falls back to a Headroom proxy at `http://127.0.0.1:8787` for cache misses.
- All operations log to `${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl` for cross-session analytics.
- Core implementation lives in [`headroom/ccr/mcp_server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/mcp_server.py), with CLI glue in [`headroom/cli/mcp.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/mcp.py).

## Frequently Asked Questions

### What are the three tools exposed by the Headroom MCP server?

The server exposes `headroom_compress`, which compresses content and returns a content hash; `headroom_retrieve`, which fetches original content by hash from the local store or proxy; and `headroom_stats`, which aggregates session statistics across all MCP instances by reading the shared JSONL stats file.

### How does the server handle retrieval when content isn't in the local store?

If `check_proxy=True` (the default) and `httpx` is installed, the `_retrieve_content` method in [`headroom/ccr/mcp_server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/mcp_server.py) automatically queries the Headroom proxy via `POST /v1/retrieve` when the local `CompressionStore` misses a lookup, returning the proxy-sourced content with source metadata.

### Can I run the MCP server without the Headroom proxy?

Yes. The server runs in stand-alone mode using only the local `CompressionStore` defined in [`headroom/cache/compression_store.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cache/compression_store.py). The proxy is optional and only used as a fallback for retrieval when the requested hash is not found locally.

### Where are session statistics stored?

All MCP instances append events to `${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl`, allowing `headroom_stats` to aggregate data across multiple processes and sub-agents that may run their own MCP server instances, as implemented in the `_append_shared_event` helper in [`headroom/ccr/mcp_server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/mcp_server.py).