{"record":{"id":"ba548563c3340be1","repo":"headroomlabs-ai/headroom","slug":"error-mcp-dependencies-not-installed-e","errorCode":null,"errorMessage":"Error: MCP dependencies not installed: {e}","messagePattern":"Error: MCP dependencies not installed: (.+?)","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/mcp.py","lineNumber":356,"sourceCode":"    This command is typically invoked by Claude Code via the MCP config,\n    not run directly. It starts the MCP server with stdio by default or\n    Streamable HTTP when requested.\n\n    \\b\n    For manual testing:\n        headroom mcp serve --debug\n        headroom mcp serve --transport http --host 127.0.0.1 --port 8788 --path /mcp\n    \"\"\"\n    import asyncio\n    import logging\n\n    # Check for MCP SDK\n    try:\n        from headroom.ccr.mcp_server import create_ccr_mcp_server\n    except ImportError as e:\n        click.echo(f\"Error: MCP dependencies not installed: {e}\", err=True)\n        click.echo(\"Install with: pip install 'headroom-ai[mcp]'\", err=True)\n        raise SystemExit(1) from None\n\n    if debug:\n        logging.basicConfig(\n            level=logging.DEBUG,\n            format=\"%(asctime)s - %(name)s - %(levelname)s - %(message)s\",\n        )\n    else:\n        # Minimal logging for MCP (stdout is used for protocol)\n        logging.basicConfig(\n            level=logging.WARNING,\n            format=\"%(levelname)s: %(message)s\",\n        )\n\n    transport = transport.lower()\n\n    # Use default if not specified\n    effective_proxy_url = proxy_url or DEFAULT_PROXY_URL\n","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/mcp.py#L338-L374","documentation":"`headroom mcp serve` imports create_ccr_mcp_server from headroom.ccr.mcp_server; that module pulls the MCP SDK transitively. On ImportError the CLI prints the missing-dependency error with the underlying exception text and the [mcp] extra hint, then exits 1 before starting any server. It is a startup-time guard, so nothing is listening on the requested host/port when you see it.","triggerScenarios":"Running `headroom mcp serve [--transport http ...]` in an environment lacking the mcp package (or a broken transitive dep), causing headroom.ccr.mcp_server import to fail.","commonSituations":"Bare headroom-ai install used as an MCP server; venv drift after mcp was removed; pip resolver downgrading mcp below the version headroom's server module needs.","solutions":["pip install 'headroom-ai[mcp]' in the serving environment","Read the '{e}' detail — if a transitive package (e.g. anyio/starlette pin) failed, fix that pin","Confirm the right interpreter: `headroom --version` vs `which python` in your service unit / wrapper script","For systemd/docker deployments, add the extra in the image build, not at runtime"],"exampleFix":"# before\n$ headroom mcp serve --transport http --port 8788\n# Error: MCP dependencies not installed: ...\n\n# after\n$ pip install 'headroom-ai[mcp]'\n$ headroom mcp serve --transport http --port 8788","handlingStrategy":"validation","validationCode":"try:\n    from headroom.ccr.mcp_server import create_ccr_mcp_server  # noqa: F401\n    READY = True\nexcept ImportError as e:\n    READY = False\n    REASON = str(e)\n\nif not READY:\n    raise SystemExit(f\"cannot serve MCP: {REASON}; pip install 'headroom-ai[mcp]'\")","typeGuard":null,"tryCatchPattern":"try:\n    from headroom.ccr.mcp_server import create_ccr_mcp_server\nexcept ImportError as e:\n    logging.getLogger(__name__).critical(\"mcp extra missing: %s\", e)\n    sys.exit(1)","preventionTips":["Bake 'headroom-ai[mcp]' into service images at build time","Health-check the import in the service entrypoint before binding the port","Keep the mcp SDK version pinned to a range headroom supports"],"tags":["cli","mcp","serve","optional-dependencies","importerror"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}