Headroom exposes an MCP server that integrates the Python Headroom toolchain as an inside-the-MCP proxy for LLM tool usage. The MCP server enables Claude Code integration and leverages Headroom’s compression and learning capabilities to optimize tool calls and responses. You can connect your Claude Code or Claude Code-compatible proxy workflow to the Headroom MCP endpoint and let it route tool outputs through Headroom’s compressions, learnings, and context optimization pipeline. Typical usage patterns involve routing tool invocations through the MCP to benefit from automatic token savings, improved context management, and corrective feedback when tools underperform, all while preserving exact recoverability of omitted information when needed. The server exposes capabilities such as compress, learn, and integration helpers that can be invoked by your MCP client to enhance LLM interactions with external tools.

Prerequisites:

• Python 3.8+ (recommended 3.9+)
• pip (or pipx) available in your environment
• Optional: a virtual environment to isolate dependencies

Installation steps:

1. Create and activate a Python environment (optional but recommended): python -m venv venv source venv/bin/activate # on macOS/Linux .\venv\Scripts\activate # on Windows

2. Install Headroom with all optional dependencies (this includes the MCP integrations and tooling): pip install "headroom-ai[all]"

3. Verify installation and availability of the MCP module: python -m pip show headroom-ai

   Ensure the package is installed and you can access the mcp entrypoint

4. Run the MCP server (as defined in mcp_config): python -m headroom.mcp

   Or invoke via your container/orchestrator using the command/args from mcp_config

5. Optional: configure environment variables and ports as needed for your deployment: HEADROOM_MCP_PORT=8080 HEADROOM_MCP_BIND=0.0.0.0

6. If you’re deploying in Docker, you can adapt the command to a container run aligned with the mcp_config: docker run -i headroom-mcp:latest

Note:

• The exact module path may vary depending on how you structure your runtime environment. If your installation uses a different entrypoint, adjust the -m module name accordingly (e.g., headroom.mcp or headroom.mcp_server).
• For production, consider running behind a reverse proxy and enabling TLS termination, and configure authentication as appropriate for your MCP client ecosystem.

Tips and common issues:

• Ensure Python 3.8+ is used; older interpreters may fail due to typing or dependency requirements.
• When updating headroom-ai, re-check the MCP module path in case the entrypoint changes between releases.
• If you see port binding issues, check that HEADROOM_MCP_BIND is set to a routable interface and that the port is not in use by another process.
• Environment variables can customize behavior like port, binding address, and runtime options; document and version them for reproducibility.
• The MCP server integrates with Claude Code workflows via the MCP interface; ensure your MCP client is configured to target the headroom MCP endpoint and to handle any compression/learning callbacks as per Headroom’s guidance.
• If you run into import or dependency errors, verify that your environment’s PATH and PYTHONPATH include the site-packages directory where headroom-ai is installed.