# How to Set Up Headroom MCP Server for Retrieval Tools: Complete Setup Guide

> Easily set up Headroom MCP server for retrieval tools. Install, register, and serve headroom_retrieve, headroom_compress, and headroom_stats with simple commands. Get started now.

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

---

**Run `pip install "headroom-ai[mcp]"`, register the server with `headroom mcp install`, and start it with `headroom mcp serve` to expose `headroom_retrieve`, `headroom_compress`, and `headroom_stats` to any MCP-compatible host.**

The `chopratejas/headroom` repository provides a lightweight, stdio-based MCP server that surfaces retrieval tools to AI coding assistants such as Claude Code, Cursor, and Codex. In [`headroom/ccr/mcp_server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/mcp_server.py), the `HeadroomMCPServer` class orchestrates three tools while maintaining a local `CompressionStore` and an optional proxy fallback. Setting up the Headroom MCP server for retrieval tools requires only the Python package, a one-time host registration, and launching the server process.

## Install the Headroom MCP Package

Headroom ships the MCP server as an optional extra. You can install the lightweight toolset alone or alongside the full proxy stack.

1. Install only the MCP tools:

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

```

2. Or install the proxy and MCP tools together:

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

```

The `headroom-ai[mcp]` extra includes everything required to run `headroom mcp serve` and register the server with your host, as documented in [`wiki/mcp.md`](https://github.com/chopratejas/headroom/blob/main/wiki/mcp.md).

## Register the Server with Claude Code

Registration is a one-time step that writes the MCP server configuration to your host's config file.

```bash
headroom mcp install

```

According to [`headroom/cli/mcp.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/mcp.py), the `install` sub-command writes a TOML block into Claude Code's `~/.claude/mcp.json` that points to `headroom mcp serve`. The registrar tests in [`tests/test_mcp_registry/test_codex_registrar.py`](https://github.com/chopratejas/headroom/blob/main/tests/test_mcp_registry/test_codex_registrar.py) verify the exact configuration format written by this command.

After registration, Claude Code automatically launches the server on startup and routes `headroom_retrieve` calls to it.

## Start the Headroom MCP Server

Normally, the AI host starts the server automatically. For debugging or manual use, run it directly:

```bash
headroom mcp serve --debug

```

In [`headroom/cli/mcp.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/mcp.py) (lines 330–352), the `serve` sub-command creates a `HeadroomMCPServer` via the `create_ccr_mcp_server` factory and calls `run_stdio()`. This opens a stdio transport and begins listening for JSON-RPC tool calls.

You can also verify your setup without launching a full session:

```bash
headroom mcp status

```

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

## Add a Proxy for Fallback Retrieval

Running the MCP server standalone keeps compressed content in a local `CompressionStore`. If you also run the Headroom proxy, the server falls back to the proxy when a requested hash is missing locally.

Start the proxy in a separate terminal:

```bash
headroom proxy

```

By default, the proxy listens at `http://127.0.0.1:8787`. When reachable, the MCP server's `_retrieve_content` method first queries the local store, then delegates to `_retrieve_via_proxy` via the proxy's `/v1/retrieve` endpoint if `check_proxy=True` and `httpx` is available. This dual-mode design lets the same toolset work with or without the full proxy stack.

## How Retrieval Works Under the Hood

The `headroom_retrieve` tool handles lookups through a two-tier pipeline defined in [`headroom/ccr/mcp_server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/mcp_server.py).

**Local lookup first.** The server lazily creates a `CompressionStore` (in `_get_local_store`) that holds original-to-compressed pairs with a default `MCP_SESSION_TTL = 3600` seconds. When a host sends a `headroom_retrieve` call with a hash, `_handle_retrieve` (lines 443–468) checks this store first.

**Proxy fallback.** If the hash is absent and proxy checks are enabled, the server queries the Headroom proxy. The `_retrieve_content` implementation (lines 10–38) and `_retrieve_via_proxy` handle the network round-trip, returning either the original content or a 404 to the client.

**Shared statistics.** Every compression and retrieval appends a JSON line to `${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl` through `_append_shared_event`. Because all MCP instances—including sub-agent processes—write to the same file, `headroom_stats` can aggregate cross-process metrics.

## Programmatically Create the Server

For custom scripts or tests, instantiate the server directly without the CLI:

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

# Use the default proxy URL or pass your own

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

# Run the stdio loop in an async context

await mcp_server.run_stdio()

```

The `create_ccr_mcp_server` factory in [`headroom/ccr/mcp_server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/mcp_server.py) (lines 886–898) returns a fully configured `HeadroomMCPServer` ready for `run_stdio()`.

## Invoke Retrieval from an MCP Client

Any MCP-compatible client can call the retrieval tool once the server is running. The following pseudo-code demonstrates the pattern:

```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"))

```

The MCP SDK pipes stdin/stdout automatically, so no network code is required. The server receives the request through `_handle_retrieve` and returns the content sourced from either the local store or the proxy.

## Summary

- **Install** the server with `pip install "headroom-ai[mcp]"`.
- **Register** it once via `headroom mcp install` to write the host configuration.
- **Launch** it with `headroom mcp serve` or let Claude Code start it automatically.
- **Retrieve** content by hash through `headroom_retrieve`, which checks the local `CompressionStore` first.
- **Fallback** to a running `headroom proxy` at `http://127.0.0.1:8787` when the hash is not stored locally.
- **Monitor** usage through the shared `${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl` file consumed by `headroom_stats`.

## Frequently Asked Questions

### What ports or network exposure does the MCP server require?

None. The `HeadroomMCPServer` is a stdio-only process. It communicates over stdin/stdout with the host, and any proxy communication happens over localhost HTTP to the optional `headroom proxy`. No inbound ports are opened by the MCP server itself.

### Can I use Headroom retrieval without installing the proxy?

Yes. The MCP server stores compressed content in a local `CompressionStore` (managed in [`headroom/cache/compression_store.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cache/compression_store.py)) and serves retrieval requests directly. The proxy fallback in `_retrieve_via_proxy` is optional and only triggers when `check_proxy=True`, `httpx` is installed, and a proxy is reachable.

### Where does the MCP server store session data?

It writes per-session events to `${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl`. All server instances append to this file, enabling `headroom_stats` to aggregate telemetry across parent and sub-agent processes. Compressed originals are kept in memory or the local store with a TTL defined by `MCP_SESSION_TTL`.

### How do I uninstall the MCP server from Claude Code?

Run `headroom mcp uninstall`. This reverses the registration step by removing the Headroom entry from the host's MCP configuration file, as implemented in [`headroom/cli/mcp.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/mcp.py).