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

Two fixes to get the headroom MCP server working with Claude Code CLI:

1. mcp_server.py: define CCR_TOOL_NAME inline instead of importing from
tool_injection, which triggered headroom/__init__.py -> LiteLLM -> HTTP
requests to GitHub, adding 4-5 seconds to startup time.

2. cli/mcp.py: prefer `claude mcp add -s user` when the claude CLI is
available (Claude Code CLI ≥2.x stores servers in ~/.claude/.claude.json,
not ~/.claude/mcp.json). Falls back to writing mcp.json for older versions
and the claude.ai desktop app.

3. tests/test_cli/test_mcp.py: update mock_claude_config_path fixture to
also stub out the claude CLI so install tests exercise the mcp.json
fallback path, matching the fixture's intent.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

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

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