{"record":{"id":"d4050ec37332a97c","repo":"headroomlabs-ai/headroom","slug":"mcp-sdk-not-installed-install-with-pip-install-m","errorCode":null,"errorMessage":"MCP SDK not installed. Install with: pip install mcp","messagePattern":"MCP SDK not installed\\. Install with: pip install mcp","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/ccr/mcp_server.py","lineNumber":385,"sourceCode":"                   (for content compressed by the proxy's automatic pipeline).\n    \"\"\"\n\n    def __init__(\n        self,\n        proxy_url: str = DEFAULT_PROXY_URL,\n        check_proxy: bool = True,\n    ):\n        self.proxy_url = proxy_url\n        self.check_proxy = check_proxy\n        self._http_client: httpx.AsyncClient | None = None  # type: ignore[assignment]\n        self._stats = SessionStats()\n        self._local_store: Any = None  # Lazy-initialized CompressionStore\n        self._compressor_initialized = False\n        # File read cache: path → (content_hash, ccr_hash, line_count, token_count)\n        self._file_cache: dict[str, tuple[str, str, int, int]] = {}\n\n        if not MCP_AVAILABLE or Server is None:\n            raise ImportError(\"MCP SDK not installed. Install with: pip install mcp\")\n\n        self.server: Server = Server(\"headroom\")\n        self._setup_handlers()\n\n    def _get_local_store(self) -> Any:\n        \"\"\"Get the shared compression store singleton (lazy init).\n\n        Returns the same instance the proxy and response_handler use so\n        retrieval can see content either side compressed in-process.\n        Called with no args to keep one shared config; the compress path\n        passes its own per-entry ``ttl`` at store time.\n        \"\"\"\n        if self._local_store is None:\n            from headroom.cache.compression_store import get_compression_store\n\n            self._local_store = get_compression_store()\n        return self._local_store\n","sourceCodeStart":367,"sourceCodeEnd":403,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/ccr/mcp_server.py#L367-L403","documentation":"The CCR MCP server class guards its constructor: if the optional 'mcp' package (or its Server class) is not importable (MCP_AVAILABLE is False / Server is None), __init__ raises ImportError telling you to pip install mcp. The MCP server only ships as an optional extra, so a plain headroom install cannot serve MCP sessions.","triggerScenarios":"Instantiating the CCR MCP session/server class (headroom.ccr.mcp_server) in an environment where 'import mcp' failed at module import time; e.g. calling create_ccr_mcp_server() without the extra installed.","commonSituations":"Installing bare 'headroom-ai' instead of 'headroom-ai[mcp]'; a venv where mcp was uninstalled; Python version incompatibility pulling no mcp wheel.","solutions":["Install the extra: pip install 'headroom-ai[mcp]' (or pip install mcp)","Verify with: python -c \"import mcp; from mcp.server import Server; print('ok')\"","Recreate/switch to the venv you actually run headroom from — extras are per-environment","Upgrade headroom if the mcp SDK version it requires conflicts with an existing install"],"exampleFix":"# before\nserver = create_ccr_mcp_server()  # ImportError: MCP SDK not installed\n\n# after\n# pip install 'headroom-ai[mcp]'\nserver = create_ccr_mcp_server()","handlingStrategy":"validation","validationCode":"try:\n    from mcp.server import Server  # the exact import the guard checks\n    MCP_OK = True\nexcept ImportError:\n    MCP_OK = False\n\nif not MCP_OK:\n    raise SystemExit(\"MCP extra missing — pip install 'headroom-ai[mcp]'\")","typeGuard":null,"tryCatchPattern":"try:\n    server = create_ccr_mcp_server(...)\nexcept ImportError as e:\n    if \"MCP SDK\" in str(e):\n        log.error(\"headroom[mcp] extra required for MCP serving\")\n        sys.exit(1)\n    raise","preventionTips":["Declare headroom-ai[mcp] in your project's dependencies if you serve MCP","Add a startup health check that imports mcp before binding the server","Docker: install extras at build time, never at container start"],"tags":["mcp","optional-dependencies","importerror","ccr"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}