{"record":{"id":"fd734e52d5680ba3","repo":"headroomlabs-ai/headroom","slug":"error-mcp-sdk-not-installed","errorCode":null,"errorMessage":"Error: MCP SDK not installed.","messagePattern":"Error: MCP SDK not installed\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/mcp.py","lineNumber":157,"sourceCode":"\n    \\b\n    By default this installs into every agent that has a registrar and is\n    detected on this system (Claude Code today; Cursor / Codex / Continue /\n    others added in subsequent releases). Pass ``--agent NAME`` one or more\n    times to restrict the installation.\n\n    \\b\n    Examples:\n        headroom mcp install                            # every detected agent\n        headroom mcp install --agent claude             # Claude Code only\n        headroom mcp install --proxy-url http://localhost:9000\n    \"\"\"\n    try:\n        import mcp  # noqa: F401\n    except ImportError:\n        click.echo(\"Error: MCP SDK not installed.\", err=True)\n        click.echo(\"Install with: pip install 'headroom-ai[mcp]'\", err=True)\n        raise SystemExit(1) from None\n\n    from headroom.mcp_registry import any_succeeded, format_results, install_everywhere\n\n    results = install_everywhere(\n        proxy_url=proxy_url,\n        agents=list(agents) if agents else None,\n        force=force,\n    )\n\n    if not results:\n        click.echo(\"No agents matched the requested filter.\")\n        raise SystemExit(1)\n\n    click.echo(\"Installing Headroom MCP server...\")\n    for line in format_results(\n        results,\n        verbose=True,\n        overwrite_hint=f\"headroom mcp install --proxy-url {proxy_url} --force\",","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/mcp.py#L139-L175","documentation":"`headroom mcp install` needs the MCP SDK only to validate that MCP registration is possible; it does a bare `import mcp` first. On ImportError it prints 'Error: MCP SDK not installed.' with the install hint for the [mcp] extra and exits 1 before touching any agent config. Pure dependency guard, nothing has been modified when you see it.","triggerScenarios":"Running `headroom mcp install [--agent ...]` in an environment where the mcp package is not installed.","commonSituations":"pip install headroom-ai without extras; system Python vs venv confusion; uninstalling mcp after installing headroom.","solutions":["pip install 'headroom-ai[mcp]' (equivalently pip install mcp) in the environment headroom runs from","Verify: python -c 'import mcp' using the same interpreter as `headroom`","Reinstall headroom with extras if the extra name changed across versions: pip install 'headroom-ai[mcp]' --upgrade","Re-run headroom mcp install after the install — no partial state was created"],"exampleFix":"# before\n$ headroom mcp install\n# Error: MCP SDK not installed.\n\n# after\n$ pip install 'headroom-ai[mcp]'\n$ headroom mcp install","handlingStrategy":"validation","validationCode":"try:\n    import mcp  # noqa: F401\n    MCP_OK = True\nexcept ImportError:\n    MCP_OK = False\n\nif not MCP_OK:\n    raise SystemExit(\"pip install 'headroom-ai[mcp]' before running mcp install\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Include the [mcp] extra in bootstrap scripts that call headroom mcp install","Pin interpreter: use `python -m headroom` or ensure `headroom` and pip share a venv","Cache a wheel build with extras for offline provisioning"],"tags":["cli","mcp","optional-dependencies","importerror"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}