René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"MCP Server Hangs Indefinitely After KqueueSelector Log on macOS (Python 3.12, Both STDIO \u0026 SSE)","articleBody":"\n\n**Describe the bug**\n\nWhen running an MCP server using `mcp-sdk` (both `FastMCP` and the low-level `Server` with `mcp.server.stdio.stdio_server`) on macOS with Python 3.12, the server process hangs indefinitely immediately after the `DEBUG - Using selector: KqueueSelector` log message appears. This happens during the `server.run()` or `mcp.run()` call.\n\nThe hang occurs regardless of whether the STDIO transport (`transport=\"stdio\"`) or the default web/SSE transport is used. It also occurs even with a minimal server configuration with no custom tools, resources, or plugins registered.\n\n**Environment:**\n\n*   **OS:** macOS 15 Sequoia (Darwin 24.5.0)\n*   **Python:** 3.12.9 (via Homebrew - *Please update if incorrect*)\n*   **mcp-sdk Version:** 1.6.1.dev14+babb477 (Installed via `pip install -e .` from Git main branch using `mcp @ git+https://github.com/modelcontextprotocol/python-sdk.git` in `pyproject.toml` with `hatchling` and `allow-direct-references = true`)\n*   **Key Dependencies:**\n    *   uvicorn: 0.30.3\n    *   starlette: 0.37.2\n    *   anyio: 4.9.0\n\n**To Reproduce**\n\nSteps to reproduce the behavior:\n1.  Ensure Python 3.12.9 and `mcp-sdk` (tested with version `1.6.1.dev14+babb477` installed from Git main branch) are installed in your environment on macOS.\n2.  Save the following minimal STDIO server example (based on the SDK documentation) as `mcp_stdio_test.py`:\n    ```python\n    # From https://github.com/modelcontextprotocol/python-sdk README (Low-Level Server example)\n    import mcp.server.stdio\n    import mcp.types as types\n    from mcp.server.lowlevel import NotificationOptions, Server\n    from mcp.server.models import InitializationOptions\n    import logging # Add logging\n    import asyncio # Add asyncio\n\n    # Configure logging\n    logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')\n    logger = logging.getLogger(__name__)\n\n\n    # Create a server instance\n    logger.debug(\"Creating Server instance...\")\n    server = Server(\"example-server\")\n    logger.debug(\"Server instance created.\")\n\n\n    @server.list_prompts()\n    async def handle_list_prompts() -\u003e list[types.Prompt]:\n        logger.debug(\"Handling list_prompts request...\")\n        return [\n            types.Prompt(\n                name=\"example-prompt\",\n                description=\"An example prompt template\",\n                arguments=[\n                    types.PromptArgument(\n                        name=\"arg1\", description=\"Example argument\", required=True\n                    )\n                ],\n            )\n        ]\n    logger.debug(\"list_prompts handler defined.\")\n\n\n    @server.get_prompt()\n    async def handle_get_prompt(\n        name: str, arguments: dict[str, str] | None\n    ) -\u003e types.GetPromptResult:\n        logger.debug(f\"Handling get_prompt request for: {name}\")\n        if name != \"example-prompt\":\n            raise ValueError(f\"Unknown prompt: {name}\")\n\n        return types.GetPromptResult(\n            description=\"Example prompt\",\n            messages=[\n                types.PromptMessage(\n                    role=\"user\",\n                    content=types.TextContent(type=\"text\", text=\"Example prompt text\"),\n                )\n            ],\n        )\n    logger.debug(\"get_prompt handler defined.\")\n\n\n    async def run():\n        logger.debug(\"run() function started.\")\n        async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):\n            logger.debug(\"stdio_server context entered.\")\n            init_options = InitializationOptions(\n                    server_name=\"example\",\n                    server_version=\"0.1.0\",\n                    capabilities=server.get_capabilities(\n                        notification_options=NotificationOptions(),\n                        experimental_capabilities={},\n                    ),\n                )\n            logger.debug(f\"Initialization options created: {init_options}\")\n            logger.debug(\"Attempting server.run()...\")\n            # Note: Using low-level server.run, not FastMCP's run\n            await server.run(\n                read_stream,\n                write_stream,\n                init_options\n            )\n            logger.debug(\"server.run() finished.\") # This likely won't be reached in normal operation\n\n\n    if __name__ == \"__main__\":\n        logger.info(\"Starting asyncio event loop...\")\n        try:\n            asyncio.run(run())\n        except KeyboardInterrupt:\n            logger.info(\"KeyboardInterrupt received, exiting.\")\n        except Exception as e:\n            logger.critical(f\"Unhandled exception in main loop: {e}\", exc_info=True)\n        finally:\n            logger.info(\"asyncio event loop finished.\")\n    ```\n3.  Run the script from the terminal: `python mcp_stdio_test.py`\n4.  **See error:** Observe the log output. The script hangs indefinitely after the `Attempting server.run()...` log message.\n\n**Expected behavior**\n\nThe server should successfully start, remain running, and be ready to accept MCP connections via STDIO (or SSE if run without `transport=\"stdio\"`). It should not hang during initialization.\n\n**Screenshots**\n\nN/A - The issue is a process hang, the relevant output is text logs shown below.\n\n**Desktop:**\n\n*   **OS:** macOS 15 Sequoia (Darwin 24.5.0)\n*   **Python Version:** 3.12.9 (via Homebrew - *Please update if incorrect*)\n*   **mcp-sdk Version:** 1.6.1.dev14+babb477 (Installed from Git main branch)\n*   **Key Dependencies:**\n    *   uvicorn: 0.30.3\n    *   starlette: 0.37.2\n    *   anyio: 4.9.0\n\n**Smartphone:**\n\nN/A\n\n**Additional context**\n\n*   The issue occurs with both `FastMCP().run(...)` and the low-level `Server().run(...)` implementation.\n*   The hang happens even when all custom tools, resources, plugins, and prompts defined in the application code are commented out.\n*   The issue persists whether using `mcp` installed from PyPI or directly from the Git main branch.\n*   Pinning `uvicorn[standard]` to `0.30.3` (a version used in a previously working commit) did not resolve the issue.\n*   Adding a `time.sleep(10)` before the `run()` call (which seemed to help in older commits) no longer prevents the hang.\n*   Issue #396 seems potentially related as it also involves problems with the STDIO transport, although it describes the client not detecting server termination rather than the server hanging on startup.\n\nThis strongly suggests an underlying issue within `mcp-sdk`'s core run logic or its interaction with `asyncio`/`KqueueSelector` on macOS with recent Python versions or recent `mcp-sdk` versions. The hang point after `KqueueSelector` seems critical.\n\n**Log Output Showing Hang:**\n\n```\n2025-04-21 02:17:29,965 - DEBUG - Creating Server instance...\n2025-04-21 02:17:29,966 - DEBUG - Initializing server 'example-server'\n2025-04-21 02:17:29,966 - DEBUG - Server instance created.\n2025-04-21 02:17:29,966 - DEBUG - Registering handler for PromptListRequest\n2025-04-21 02:17:29,966 - DEBUG - list_prompts handler defined.\n2025-04-21 02:17:29,966 - DEBUG - Registering handler for GetPromptRequest\n2025-04-21 02:17:29,966 - DEBUG - get_prompt handler defined.\n2025-04-21 02:17:29,966 - INFO - Starting asyncio event loop...\n2025-04-21 02:17:29,966 - DEBUG - Using selector: KqueueSelector\n2025-04-21 02:17:29,971 - DEBUG - run() function started.\n2025-04-21 02:17:29,973 - DEBUG - stdio_server context entered.\n2025-04-21 02:17:29,973 - DEBUG - Initialization options created: server_name='example' server_version='0.1.0' capabilities=ServerCapabilities(experimental={}, logging=None, prompts=PromptsCapability(listChanged=False), resources=None, tools=None) instructions=None\n2025-04-21 02:17:29,973 - DEBUG - Attempting server.run()...\n\u003c-- HANGS HERE INDEFINITELY --\u003e\n``` ","author":{"url":"https://github.com/jlcases","@type":"Person","name":"jlcases"},"datePublished":"2025-04-21T00:26:08.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":4},"url":"https://github.com/547/python-sdk/issues/547"}