The `stdio_client` hangs indefinitely on session initialization

[Shashikant86]

Initial Checks

• I confirm that I'm using the latest version of MCP Python SDK
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Description

The stdio_client hangs indefinitely on session initialization

Environment

• OS: macOS 15.2
• Python: Python 3.12.11
• MCP SDK Version: 1.16.0
• Async Library: anyio (via asyncio backend)

Description

The stdio_client() context manager hangs indefinitely when trying to initialize an MCP session over stdio. The process never completes, even when the MCP server is functioning correctly and responding to JSON-RPC requests.

Reproduction

MCP Server (works correctly)

Direct test shows server responds properly:

echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | \
  npx -y @modelcontextprotocol/server-filesystem /tmp

Output:

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"secure-filesystem-server","version":"0.2.0"}}}

MCP Client (hangs)

import asyncio
from mcp import StdioServerParameters, stdio_client
from mcp.client.session import ClientSession

async def test():
    server_params = StdioServerParameters(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    )

    async with stdio_client(server_params) as (read, write):
        session = ClientSession(read, write)
        await session.initialize()  # Hangs here forever

asyncio.run(test())

Behavior: Hangs indefinitely with no output or progress.

Error Details

After timeout (30s), the following error is raised:

ExceptionGroup: unhandled errors in a TaskGroup (2 sub-exceptions)
+-+---------------- 1 ----------------
  | Traceback (most recent call last):
  |   File "/path/to/mcp/client/stdio/__init__.py", line 162, in stdout_reader
  |     await read_stream_writer.send(session_message)
  |   File "/path/to/anyio/streams/memory.py", line 256, in send
  |     raise BrokenResourceError from None
  | anyio.BrokenResourceError
  +---------------- 2 ----------------
  | Traceback (most recent call last):
  |   File "/path/to/asyncio/tasks.py", line 520, in wait_for
  |     return await fut
  |            ^^^^^^^^^
  |   File "/path/to/mcp/client/session.py", line 151, in initialize
  |     result = await self.send_request(
  |              ^^^^^^^^^^^^^^^^^^^^^^^^
  |   File "/path/to/mcp/shared/session.py", line 272, in send_request
  |     response_or_error = await response_stream_reader.receive()
  |                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  | asyncio.exceptions.CancelledError

The stdout_reader task in stdio_client raises BrokenResourceError when trying to send parsed messages, suggesting the stdout stream from the subprocess is not being read properly.

Testing Details

What works ✅

• MCP server responds correctly to stdio input when tested directly
• Manual subprocess with asyncio.create_subprocess_exec() works
• Simple JSON-RPC over subprocess.PIPE works

What fails ❌

• stdio_client() with asyncio.run()
• stdio_client() with anyio.run()
• All MCP client examples using stdio transport
• Both with npm-based servers and Python-based servers

Impact

This bug makes the Python MCP SDK completely unusable for stdio transport on macOS, which is the primary transport method for MCP servers. This affects:

• All local development on macOS
• Any MCP adapter implementations (like GEPA's MCP adapter)

Notes

• The issue appears specific to anyio's subprocess implementation on macOS
• Windows/Linux compatibility not tested
• SSE/HTTP transports may work as alternatives but are not commonly documented or used
• The issue persists with both asyncio.run() and anyio.run() as the event loop runner

Let me know if you need more info to reproduce this issue Python 3.12.11

Example Code

import asyncio
from mcp import StdioServerParameters, stdio_client
from mcp.client.session import ClientSession

async def test():
    server_params = StdioServerParameters(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    )

    async with stdio_client(server_params) as (read, write):
        session = ClientSession(read, write)
        await session.initialize()  # Hangs here forever

asyncio.run(test())

Python & MCP Python SDK

Name: mcp
Version: 1.16.0
Summary: Model Context Protocol SDK
Author-email: 
License: MIT
Location: /Users/shashi/miniconda3/envs/mcp-adapter/lib/python3.12/site-packages
Requires: anyio, httpx, httpx-sse, jsonschema, pydantic, pydantic-settings, python-multipart, sse-starlette, starlette, uvicorn