René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Bug Report: FastMCP `RuntimeError: Received request before initialization was complete` Leading to Empty SSE Responses When Embedded in FastAPI","articleBody":"  ## Bug Report: FastMCP `RuntimeError: Received request before initialization was complete` Leading to Empty SSE Responses When Embedded in FastAPI\n\n        **Library Version:** `mcp[cli]==1.8.0` (Python SDK)\n        **Python Version:** 3.11.x\n        **Web Framework:** FastAPI (e.g., 0.100+)\n        **ASGI Server:** Uvicorn\n\n        **Problem Description:**\n\n        When embedding `FastMCP.streamable_http_app()` as a sub-application within a FastAPI application and managing its lifecycle via FastAPI's `lifespan` context manager (using `asyncio.TaskGroup` to run `FastMCP` components), we encounter a persistent `RuntimeError: Received request before initialization was complete`.\n\n        This error occurs specifically when an MCP tool is called by a client and is expected to return data via Server-Sent Events (SSE).\n        The sequence of events observed is:\n        1. Client establishes a session successfully (receives `mcp-session-id` header, often with an initial 400 \"Missing session ID\" response which is then handled).\n        2. Client makes a `tools/call` request with the valid `mcp-session-id`.\n        3. The MCP server (FastAPI with FastMCP mounted) sends HTTP 200 OK headers with `Content-Type: text/event-stream`.\n        4. **Immediately after sending the 200 OK headers, before any `event: message` or `data:` lines are sent in the SSE stream, the `mcp.server.streamable_http_manager.StreamableHTTPSessionManager` logs that it is \"shutting down.\"**\n        5. The server then logs a `RuntimeError: Received request before initialization was complete` (traceback points to `mcp/server/session.py`).\n        6. The client receives the 200 OK but with an empty response body, as the SSE stream was closed before any data events were sent.\n\n        This issue occurs even if the tool is designed to return a very simple JSON payload (e.g., `{\"result_id\": \"some_id\"}`). The tool's Python code that prepares the `List[ContentPart]` often appears not to be fully executed, or at least its return value is not successfully processed for SSE streaming due to this premature shutdown.\n\n        **Steps to Reproduce (Conceptual - based on our integration pattern):**\n\n        1.  **`app.py` (FastAPI main application):**\n            *   A global `FastMCP` instance (`mcp_server`) is created. To avoid Uvicorn port conflicts when FastMCP's internal server mechanisms are invoked, we've tried initializing `FastMCP` with `host=\"127.0.0.1\", port=0`.\n            *   Tool modules (e.g., `core_tools.py` with a simple `log_decision` tool returning `[ContentPart(text=\"...\")]`) are imported *after* the global `mcp_server` is created, so decorators use this instance.\n            *   The FastAPI `lifespan` context manager is used:\n                *   It obtains `mcp_server.streamable_http_app()` and mounts it at a sub-path (e.g., `/mcp`).\n                *   It attempts to manage the lifecycle of FastMCP's services. Our current best approach (which starts the session manager but still leads to the runtime error) involves:\n                    ```python\n                    # (Inside lifespan)\n                    # Ensure session manager is created by accessing streamable_http_app first\n                    starlette_app = mcp_server.streamable_http_app()\n                    if mcp_server._session_manager is None:\n                        raise RuntimeError(\"Session manager not initialized by streamable_http_app\")\n\n                    async with mcp_server._session_manager.run(): # Manages StreamableHTTPSessionManager\n                        # We previously also tried running mcp_server.run_streamable_http_async()\n                        # in an asyncio.TaskGroup here, but that method unconditionally\n                        # tries to start its own Uvicorn server, causing port conflicts\n                        # unless host/port in FastMCP settings are None/0.\n                        # However, even then, the \"initialization not complete\" error persists\n                        # for actual data return.\n                        logger.info(\"FastAPI Lifespan: FastMCP components (attempted) started.\")\n                        yield\n                    ```\n        2.  **Client Script:**\n            *   Establishes a session with the `/mcp/mcp/` endpoint (receives `mcp-session-id` header).\n            *   Makes a `tools/call` POST request to `/mcp/mcp/` with the `mcp-session-id` header, targeting a simple tool that should return `List[ContentPart]`.\n            *   Client expects an SSE stream.\n\n        **Expected Behavior:**\n\n        The tool executes, and its `List[ContentPart]` result is serialized and streamed back to the client as SSE `data:` payloads after the initial 200 OK and SSE headers. The `StreamableHTTPSessionManager` should remain active throughout this process for the given session.\n\n        **Actual Behavior:**\n\n        *   HTTP 200 OK is received by the client.\n        *   `Content-Type: text/event-stream` header is present.\n        *   The response body is empty.\n        *   Server logs show `StreamableHTTPSessionManager` shutting down.\n        *   Server logs show `RuntimeError: Received request before initialization was complete` originating from `mcp/server/session.py`.\n        *   The actual tool code that generates the `List[ContentPart]` might not be reached or its result is not processed.\n\n        **Analysis \u0026 Hypothesis:**\n\n        It appears there's a race condition or an incomplete initialization of a required component (possibly the `RequestProcessor` or its internal `anyio.TaskGroup`) when FastMCP is embedded and its lifecycle is managed externally by FastAPI's lifespan. The `StreamableHTTPSessionManager` (started via `async with _session_manager.run()`) might be ready to accept HTTP connections and send initial headers, but the underlying machinery to fully process the tool call and stream results is not yet (or no longer) in a ready state when the request is internally dispatched after the initial HTTP handshake.\n\n        The method `FastMCP.run_streamable_http_async()` is documented to \"initialize all necessary components, including the RequestProcessor and its task group.\" However, this method also unconditionally starts its own Uvicorn server. We have not found parameters for `run_streamable_http_async()` or the `FastMCP` constructor that would allow it to perform *only* the service/task-group initializations without starting a new HTTP server instance, which is necessary for embedding within an existing FastAPI application managed by its own Uvicorn process.\n\n        The example `mcp/server/streamable_http_stateless_demo/server.py` in the SDK shows direct use of `StreamableHTTPSessionManager` with `mcp.server.lowlevel.Server`, and its lifespan correctly manages `session_manager.run()`. It seems the `FastMCP` wrapper around these components might have an issue when its `run_streamable_http_async` is not the primary server entry point.\n\n        **Question to SDK Authors:**\n\n        1.  What is the recommended pattern to fully initialize all FastMCP services (including `RequestProcessor` and its task group) when `FastMCP.streamable_http_app()` is mounted as a sub-application in a parent ASGI framework like FastAPI, ensuring that FastMCP does not attempt to start its own HTTP server?\n        2.  Is the `RuntimeError: Received request before initialization was complete` indicative of a specific component's lifecycle not being correctly managed in such an embedded scenario?\n        3.  Are there specific parameters for `FastMCP.__init__` or an alternative to `run_streamable_http_async` for performing a \"service-only\" initialization suitable for embedding?\n\n        Any guidance or clarification on the intended lifecycle management for embedded `FastMCP` instances would be greatly appreciated. We believe resolving this will significantly improve its usability with frameworks like FastAPI.\n\n        Thank you for your work on this SDK.\n","author":{"url":"https://github.com/jasny6969","@type":"Person","name":"jasny6969"},"datePublished":"2025-05-16T17:12:07.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":5},"url":"https://github.com/737/python-sdk/issues/737"}