Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(mcp): use claude mcp add for install and fix startup import

Claude Code Botc078faa35378
diff --git a/headroom/ccr/mcp_server.py b/headroom/ccr/mcp_server.py
index 937fa813a..b4693dc6d 100644
--- a/headroom/ccr/mcp_server.py
+++ b/headroom/ccr/mcp_server.py
@@ -55,7 +55,9 @@ except ImportError:
HTTPX_AVAILABLE = False
httpx = None # type: ignore[assignment]
-from .tool_injection import CCR_TOOL_NAME
+# Defined inline to avoid importing the full headroom package (which loads LiteLLM
+# and makes HTTP requests to GitHub, adding 4-5 seconds to startup time).
+CCR_TOOL_NAME = "headroom_retrieve"
logger = logging.getLogger("headroom.ccr.mcp")
diff --git a/headroom/cli/mcp.py b/headroom/cli/mcp.py
index 318abeafc..c8b113caa 100644
--- a/headroom/cli/mcp.py
+++ b/headroom/cli/mcp.py
@@ -95,8 +95,8 @@ def mcp_install(proxy_url: str, force: bool) -> None:
"""Install Headroom MCP server into Claude Code config.
\b
- This adds headroom to ~/.claude/mcp.json so Claude Code can use
- the headroom_retrieve tool for CCR (Compress-Cache-Retrieve).
+ This registers headroom with Claude Code so it can use the
+ headroom_retrieve tool for CCR (Compress-Cache-Retrieve).
\b
Example:
@@ -111,38 +111,81 @@ def mcp_install(proxy_url: str, force: bool) -> None:
click.echo("Install with: pip install 'headroom-ai[mcp]'", err=True)
raise SystemExit(1) from None
- config = load_mcp_config()
-
- # Check if already configured
- if "headroom" in config.get("mcpServers", {}) and not force:
- click.echo("Headroom MCP is already configured in Claude Code.")
- click.echo("Use --force to overwrite, or 'headroom mcp uninstall' first.")
- raise SystemExit(0)
-
- # Build server config
command = get_headroom_command()
+ env: dict[str, str] = {}
+ if proxy_url != DEFAULT_PROXY_URL:
+ env["HEADROOM_PROXY_URL"] = proxy_url
+
+ # Prefer `claude mcp add` (Claude Code CLI ≥2.x stores servers in
+ # ~/.claude/.claude.json, which is what `claude mcp list` reads).
+ claude_cli = shutil.which("claude")
+ used_claude_cli = False
+ if claude_cli:
+ import subprocess
+
+ # Check if already registered
+ result = subprocess.run(
+ [claude_cli, "mcp", "get", "headroom"],
+ capture_output=True,
+ text=True,
+ )
+ already_registered = result.returncode == 0
+
+ if already_registered and not force:
+ click.echo("Headroom MCP is already configured in Claude Code.")
+ click.echo("Use --force to overwrite, or 'headroom mcp uninstall' first.")
+ raise SystemExit(0)
+
+ if already_registered and force:
+ subprocess.run(
+ [claude_cli, "mcp", "remove", "headroom", "-s", "user"],
+ capture_output=True,
+ )
+
+ add_cmd = [claude_cli, "mcp", "add", "headroom", "-s", "user"]
+ for k, v in env.items():
+ add_cmd += ["-e", f"{k}={v}"]
+ add_cmd += ["--", *command]
+
+ result = subprocess.run(add_cmd, capture_output=True, text=True)
+ if result.returncode == 0:
+ used_claude_cli = True
+ else:
+ click.echo(
+ f"Warning: 'claude mcp add' failed ({result.stderr.strip()}), "
+ "falling back to mcp.json.",
+ err=True,
+ )
+
+ if not used_claude_cli:
+ # Fallback: write ~/.claude/mcp.json (used by older Claude Code versions
+ # and the Claude.ai desktop app).
+ config = load_mcp_config()
- # Add proxy URL as environment variable if non-default
- server_config: dict = {
- "command": command[0],
- "args": command[1:],
- }
+ if "headroom" in config.get("mcpServers", {}) and not force:
+ click.echo("Headroom MCP is already configured in Claude Code.")
+ click.echo("Use --force to overwrite, or 'headroom mcp uninstall' first.")
+ raise SystemExit(0)
- if proxy_url != DEFAULT_PROXY_URL:
- server_config["env"] = {"HEADROOM_PROXY_URL": proxy_url}
+ server_config: dict = {"command": command[0], "args": command[1:]}
+ if env:
+ server_config["env"] = env
- # Update config
- if "mcpServers" not in config:
- config["mcpServers"] = {}
- config["mcpServers"]["headroom"] = server_config
+ if "mcpServers" not in config:
+ config["mcpServers"] = {}
+ config["mcpServers"]["headroom"] = server_config
+ save_mcp_config(config)
- # Save
- save_mcp_config(config)
+ config_note = (
+ "Registered via: claude mcp add (scope: user)"
+ if used_claude_cli
+ else f"Configuration written to: {MCP_CONFIG_PATH}"
+ )
click.echo(f"""
✓ Headroom MCP server installed!
-Configuration written to: {MCP_CONFIG_PATH}
+{config_note}
Next steps:
1. Start the Headroom proxy (if not running):
diff --git a/tests/test_cli/test_mcp.py b/tests/test_cli/test_mcp.py
index 702175b4a..bb7e3695c 100644
--- a/tests/test_cli/test_mcp.py
+++ b/tests/test_cli/test_mcp.py
@@ -39,11 +39,26 @@ def temp_claude_dir(tmp_path):
@pytest.fixture
def mock_claude_config_path(temp_claude_dir):
- """Patch the MCP config path to use temp directory."""
+ """Patch the MCP config path to use temp directory.
+
+ Also mocks the claude CLI as absent so tests exercise the mcp.json
+ fallback path rather than the `claude mcp add` path.
+ """
+ import shutil as _shutil
+
config_path = temp_claude_dir / "mcp.json"
+ # Capture the original function reference before patching so we don't recurse.
+ _real_which = _shutil.which
+
+ def which_no_claude(cmd):
+ if cmd == "claude":
+ return None
+ return _real_which(cmd)
+
with patch("headroom.cli.mcp.MCP_CONFIG_PATH", config_path):
with patch("headroom.cli.mcp.CLAUDE_CONFIG_DIR", temp_claude_dir):
- yield config_path
+ with patch("headroom.cli.mcp.shutil.which", side_effect=which_no_claude):
+ yield config_path
@pytest.fixture