Graphify-Labs/graphify · error · ImportError

HTTP transport needs the mcp extra (mcp + starlette + uvicor

Error message

HTTP transport needs the mcp extra (mcp + starlette + uvicorn). Run: pip install "graphifyy[mcp]"

What it means

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.

Source

Thrown at graphify/serve.py:2140

    Split out from :func:`serve_http` (which blocks on uvicorn) so the wiring
    can be exercised with an in-process ASGI test client.

    ``session_timeout`` reaps stateful sessions idle for that many seconds so a
    long-running shared server does not leak memory when IDE clients disconnect
    without sending a DELETE. ``None`` (or <= 0) disables reaping; it is forced
    to ``None`` in stateless mode, which has no sessions to reap.
    """
    try:
        import contextlib

        from starlette.applications import Starlette
        from starlette.middleware import Middleware
        from starlette.routing import Route

        from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
        from mcp.server.transport_security import TransportSecuritySettings
    except ImportError as e:
        raise ImportError(
            'HTTP transport needs the mcp extra (mcp + starlette + uvicorn). '
            'Run: pip install "graphifyy[mcp]"'
        ) from e

    # A blank key (e.g. --api-key "" or an empty GRAPHIFY_API_KEY) must not be
    # mistaken for "auth on" — normalize it to None so the gate is unambiguous.
    api_key = (api_key or "").strip() or None

    server = _build_server(graph_path)

    # DNS-rebinding protection. When the operator binds a wildcard address they
    # are intentionally exposing the server, so accept any Host header; for a
    # loopback/specific bind, restrict Host to that address (with and without
    # the port) plus the localhost aliases.
    if host in ("0.0.0.0", "::", ""):
        security = TransportSecuritySettings(enable_dns_rebinding_protection=False)
    else:
        allowed = {host, "localhost", "127.0.0.1"}

View on GitHub (pinned to 7fe58b0b0f)

Solutions

1. pip install "graphifyy[mcp]" which pulls mcp + starlette + uvicorn together.
2. Upgrade mcp to a version that ships mcp.server.streamable_http_manager (check python -c "from mcp.server.streamable_http_manager import StreamableHTTPSessionManager").
3. Use stdio transport (graphify serve) instead if you only have the base mcp package.
4. Verify no shadowing starlette/mcp directories exist on sys.path.

Example fix

# before
pip install graphifyy mcp
graphify serve-http  # ImportError

# after
pip install "graphifyy[mcp]"
graphify serve-http

def http_stack_available() -> bool:
    try:
        import starlette.applications  # noqa: F401
        from mcp.server.streamable_http_manager import StreamableHTTPSessionManager  # noqa: F401
        from mcp.server.transport_security import TransportSecuritySettings  # noqa: F401
    except ImportError:
        return False
    return True

def can_serve_http() -> bool:
    return http_stack_available() and uvicorn_available()

try:
        app = _build_http_app(...)
except ImportError as e:
    if 'mcp extra' in str(e):
        log.error("HTTP transport unavailable: pip install \"graphifyy[mcp]\"")
        fall_back_to_stdio()  # explicit fallback choice, documented
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• mcp not installed. Run: pip install "graphifyy[mcp]"
• ingest: failed to fetch {url!r}: {exc}
• graphify install is incomplete: missing always-on block '{ba
• the '{pkg}' package is required for this backend but is not
• the 'anthropic' package is required for this backend but is

AI-assisted analysis of Graphify-Labs/graphify@7fe58b0b0f (2026-08-14). Data as JSON: /api/errors/e92a5e2b25f179c0. Report an issue: GitHub.