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

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 (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.

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:

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, 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:

headroom mcp serve --debug

The serve sub-command in 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:

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:

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:

headroom mcp status

This reports SDK availability, Claude config path, proxy URL, and proxy health (sourced from headroom/cli/mcp.py, lines 164-168).

Use the retrieval tool from an MCP client:

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, with CLI glue in 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 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. 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.

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