{"record":{"id":"e92a5e2b25f179c0","repo":"Graphify-Labs/graphify","slug":"http-transport-needs-the-mcp-extra-mcp-starlett","errorCode":null,"errorMessage":"HTTP transport needs the mcp extra (mcp + starlette + uvicorn). Run: pip install \"graphifyy[mcp]\"","messagePattern":"HTTP transport needs the mcp extra \\(mcp \\+ starlette \\+ uvicorn\\)\\. Run: pip install \"graphifyy\\[mcp\\]\"","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"graphify/serve.py","lineNumber":2140,"sourceCode":"    Split out from :func:`serve_http` (which blocks on uvicorn) so the wiring\n    can be exercised with an in-process ASGI test client.\n\n    ``session_timeout`` reaps stateful sessions idle for that many seconds so a\n    long-running shared server does not leak memory when IDE clients disconnect\n    without sending a DELETE. ``None`` (or <= 0) disables reaping; it is forced\n    to ``None`` in stateless mode, which has no sessions to reap.\n    \"\"\"\n    try:\n        import contextlib\n\n        from starlette.applications import Starlette\n        from starlette.middleware import Middleware\n        from starlette.routing import Route\n\n        from mcp.server.streamable_http_manager import StreamableHTTPSessionManager\n        from mcp.server.transport_security import TransportSecuritySettings\n    except ImportError as e:\n        raise ImportError(\n            'HTTP transport needs the mcp extra (mcp + starlette + uvicorn). '\n            'Run: pip install \"graphifyy[mcp]\"'\n        ) from e\n\n    # A blank key (e.g. --api-key \"\" or an empty GRAPHIFY_API_KEY) must not be\n    # mistaken for \"auth on\" — normalize it to None so the gate is unambiguous.\n    api_key = (api_key or \"\").strip() or None\n\n    server = _build_server(graph_path)\n\n    # DNS-rebinding protection. When the operator binds a wildcard address they\n    # are intentionally exposing the server, so accept any Host header; for a\n    # loopback/specific bind, restrict Host to that address (with and without\n    # the port) plus the localhost aliases.\n    if host in (\"0.0.0.0\", \"::\", \"\"):\n        security = TransportSecuritySettings(enable_dns_rebinding_protection=False)\n    else:\n        allowed = {host, \"localhost\", \"127.0.0.1\"}","sourceCodeStart":2122,"sourceCodeEnd":2158,"githubUrl":"https://github.com/Graphify-Labs/graphify/blob/7fe58b0b0f3873be9a21c30106b8b8527c353aa6/graphify/serve.py#L2122-L2158","documentation":"Raised in _build_http_app (graphify/serve.py) when importing the HTTP stack (starlette applications/middleware/routing, mcp.server.streamable_http_manager.StreamableHTTPSessionManager, mcp.server.transport_security.TransportSecuritySettings) fails. The HTTP transport needs more than the base mcp package — starlette (and uvicorn for serving) — hence the broader [mcp] extra named in the message.","triggerScenarios":"Calling serve_http / _build_http_app where mcp is installed but starlette or uvicorn is missing, or where the installed mcp version predates streamable_http_manager / transport_security modules.","commonSituations":"Installing plain `mcp` alongside graphifyy without extras; older mcp versions (<1.x streamable-http era) lacking the StreamableHTTPSessionManager module; environments that strip starlette as an unused transitive dep.","solutions":["pip install \"graphifyy[mcp]\" which pulls mcp + starlette + uvicorn together.","Upgrade mcp to a version that ships mcp.server.streamable_http_manager (check python -c \"from mcp.server.streamable_http_manager import StreamableHTTPSessionManager\").","Use stdio transport (graphify serve) instead if you only have the base mcp package.","Verify no shadowing starlette/mcp directories exist on sys.path."],"exampleFix":"# before\npip install graphifyy mcp\ngraphify serve-http  # ImportError\n\n# after\npip install \"graphifyy[mcp]\"\ngraphify serve-http","handlingStrategy":"validation","validationCode":"def http_stack_available() -> bool:\n    try:\n        import starlette.applications  # noqa: F401\n        from mcp.server.streamable_http_manager import StreamableHTTPSessionManager  # noqa: F401\n        from mcp.server.transport_security import TransportSecuritySettings  # noqa: F401\n    except ImportError:\n        return False\n    return True","typeGuard":"def can_serve_http() -> bool:\n    return http_stack_available() and uvicorn_available()","tryCatchPattern":"try:\n        app = _build_http_app(...)\nexcept ImportError as e:\n    if 'mcp extra' in str(e):\n        log.error(\"HTTP transport unavailable: pip install \\\"graphifyy[mcp]\\\"\")\n        fall_back_to_stdio()  # explicit fallback choice, documented\n    else:\n        raise","preventionTips":["Install the whole [mcp] extra rather than hand-picking mcp/starlette.","Pin a modern mcp version (streamable-http era) in requirements.","Fail fast at startup with an availability check instead of mid-request."],"tags":["mcp","http","installation","dependencies"],"backgroundTag":null,"analyzedSha":"7fe58b0b0f3873be9a21c30106b8b8527c353aa6","analyzedAt":"2026-08-14T19:23:21.323Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}