The `stdio_client` hangs indefinitely on session initialization

[Shashikant86]

Initial Checks

• [x] I confirm that I'm using the latest version of MCP Python SDK
• [x] 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

[SimplyKnownAsG]

I also run into this (really long initialize() for @modelcontextprootocol/server-filesystem) sometimes, and very consistently on my AL2 linux machine. I do not have issues locally. I ran npm i -g @modelcontextprootocol/server-filesystem and changed the args to point to the installed binary directly, and the issue went away. I don't know enough about npx to recommend a better fix. I also tried using npx --no-install, but that didn't resolve the issue either.

[sKumaraguru]

This looks like a miss from the development team. I had the same issue. And I delved into the mcp package code to write a fix myself. In the mcp/shared/session.py file, in the async def send_request method change line 275 from

response_or_error = await response_stream_reader.receive()

to

response_or_error = await self._read_stream.receive()

It should be using the mcp sever's read stream, instead of using a random anyio stream (like it's done in the code today)

Along with that change line 289 from

raise McpError(response_or_error.error)

to

raise McpError(response_or_error.message.root.error)

And line 291 from

return result_type.model_validate(response_or_error.result)

to

return result_type.model_validate(response_or_error.message.root.result)

With these changes, the issue is resolved. @felixweinberger

[CaseyHaralson]

This looks like a miss from the development team. I had the same issue. And I delved into the mcp package code to write a fix myself. In the mcp/shared/session.py file, in the async def send_request method change line 275 from

response_or_error = await response_stream_reader.receive()

to

response_or_error = await self._read_stream.receive()

It should be using the mcp sever's read stream, instead of using a random anyio stream (like it's done in the code today)

Along with that change line 289 from

raise McpError(response_or_error.error)

to

raise McpError(response_or_error.message.root.error)

And line 291 from

return result_type.model_validate(response_or_error.result)

to

return result_type.model_validate(response_or_error.message.root.result)

With these changes, the issue is resolved. @felixweinberger

This worked for me too. Thanks!

[sKumaraguru]

@felixweinberger Will this issue be resolved soon? Any ETA?