Initialize call hangs forever if MCP server does not return a `Content-Type: text/plain`

[HenriChabert]

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

We had some timeouts on our server while using MCP client from the SDK.
When users try to integrate our client with their MCP server, we do an initialize call to the server and we are waiting infinitely to the following:

sync with self:
 ...

After investigation, it seems the error happens when the MCP server is misconfigured, and returns something different than Content-Type: text/event-stream as a response from the initialize call.

Although it is on the server side, the client should be able to fail immediately with a understandable error to warn the user something went wrong with the server's initialize output.

Example Code

# server.py

from http.server import BaseHTTPRequestHandler, HTTPServer

class PlainTextHandler(BaseHTTPRequestHandler):
 def do_POST(self):
 length = int(self.headers.get("Content-Length", 0))
 self.rfile.read(length)

 body = b"this is not json"
 self.send_response(200)
 self.send_header("Content-Type", "text/plain")
 self.send_header("Content-Length", str(len(body)))
 self.end_headers()
 self.wfile.write(body)

 def log_message(self, format, *args):
 print(f"[server] {format % args}")

server = HTTPServer(("localhost", 9000), PlainTextHandler)
print("[server] listening on http://localhost:9000")
server.serve_forever()

# client.py
import asyncio
import mcp
from mcp.client.streamable_http import streamable_http_client

async def main():
 print("connecting…")
 async with streamable_http_client("http://localhost:9000/mcp") as (
 read_stream, write_stream, _,
 ):
 async with mcp.ClientSession(read_stream, write_stream) as session:
 await session.initialize() # ← hangs here forever

 print("done (you should never see this)")

Python & MCP Python SDK

- Python 3.12.12
- MCP - 1.27.0

[vishal-vanam]

I'd like to work on this. Will submit a PR shortly.

[mcp-claude]

confirmed on v1.x; fixed on main in commit 7c7c13b (PR #2005).

root cause: _handle_unexpected_content_type in v1.x sends a bare ValueError to the read stream instead of a JSONRPCError with the matching request ID. ClientSession.initialize() waits for a response keyed to its request ID — the raw exception is never matched, so the call blocks forever.

workaround: none short of setting an asyncio.timeout or httpx timeout around the call.

repro script (repro.py)

"""
Repro for issue #2432: initialize hangs when server returns Content-Type: text/plain.
"""
import asyncio
import threading
from http.server import BaseHTTPRequestHandler, HTTPServer

import mcp
from mcp.client.streamable_http import streamable_http_client


class PlainTextHandler(BaseHTTPRequestHandler):
 def do_POST(self):
 length = int(self.headers.get("Content-Length", 0))
 self.rfile.read(length)
 body = b"this is not json"
 self.send_response(200)
 self.send_header("Content-Type", "text/plain")
 self.send_header("Content-Length", str(len(body)))
 self.end_headers()
 self.wfile.write(body)

 def log_message(self, format, *args):
 pass


def start_server():
 server = HTTPServer(("localhost", 19000), PlainTextHandler)
 server.serve_forever()


async def main():
 t = threading.Thread(target=start_server, daemon=True)
 t.start()
 await asyncio.sleep(0.2)

 print("connecting...")
 try:
 async with asyncio.timeout(5):
 async with streamable_http_client("http://localhost:19000/mcp") as (
 read_stream, write_stream, _,
 ):
 async with mcp.ClientSession(read_stream, write_stream) as session:
 await session.initialize()
 print("UNEXPECTED: completed without error")
 except TimeoutError:
 print("REPRODUCED: timed out after 5 seconds (hung on initialize)")
 except Exception as e:
 print(f"GOT ERROR (not a hang): {type(e).__name__}: {e}")


asyncio.run(main())

terminal output

# on origin/v1.x
$ uv run python repro.py
Unexpected content type: text/plain
connecting...
REPRODUCED: timed out after 5 seconds (hung on initialize)

# on origin/main (commit 3d7b311)
$ uv run python repro.py
connecting...
GOT ERROR (not a hang): ExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception)

code path

v1.x _handle_post_request (streamable_http.py ~line 371):

else:
 await self._handle_unexpected_content_type(content_type, ctx.read_stream_writer)

v1.x _handle_unexpected_content_type (~line 508):

await read_stream_writer.send(ValueError(error_msg)) # ← bare exception, no request ID

main fix in commit 7c7c13b (same branch point, _handle_post_request):

else:
 error_data = ErrorData(code=INVALID_REQUEST, message=f"Unexpected content type: {content_type}")
 error_msg = SessionMessage(JSONRPCError(jsonrpc="2.0", id=message.id, error=error_data))
 await ctx.read_stream_writer.send(error_msg) # ← carries request ID, session resolves it

suggested fix

--- a/src/mcp/client/streamable_http.py
+++ b/src/mcp/client/streamable_http.py
@@ -28,6 +28,7 @@ from mcp.shared._httpx_utils import (
 )
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
 from mcp.types import (
+ INVALID_REQUEST,
 ErrorData,
 InitializeResult,
 JSONRPCError,
@@ -368,10 +369,11 @@ class StreamableHTTPTransport:
 elif content_type.startswith(SSE):
 await self._handle_sse_response(response, ctx, is_initialization)
 else:
- await self._handle_unexpected_content_type( # pragma: no cover
- content_type, # pragma: no cover
- ctx.read_stream_writer, # pragma: no cover
- ) # pragma: no cover
+ await self._handle_unexpected_content_type(
+ content_type,
+ ctx.read_stream_writer,
+ message.root.id,
+ )
 
 @@ -501,11 +503,18 @@ class StreamableHTTPTransport:
 self,
 content_type: str,
 read_stream_writer: StreamWriter,
- ) -> None: # pragma: no cover
+ request_id: RequestId,
+ ) -> None:
 """Handle unexpected content type in response."""
- error_msg = f"Unexpected content type: {content_type}" # pragma: no cover
- logger.error(error_msg) # pragma: no cover
- await read_stream_writer.send(ValueError(error_msg)) # pragma: no cover
+ error_msg = f"Unexpected content type: {content_type}"
+ logger.error(error_msg)
+ jsonrpc_error = JSONRPCError(
+ jsonrpc="2.0",
+ id=request_id,
+ error=ErrorData(code=INVALID_REQUEST, message=error_msg),
+ )
+ session_message = SessionMessage(JSONRPCMessage(jsonrpc_error))
+ await read_stream_writer.send(session_message)

test to verify: test_unexpected_content_type_raises_not_hangs in tests/shared/test_streamable_http.py — uses httpx.MockTransport returning text/plain, asserts anyio.CancelScope.cancelled_caught is False (i.e., initialize() raised quickly rather than hanging to the 5-second deadline).

[Christian-Sidak]

Opened a fix in #2472 -- adds a regression test verifying that initialize() raises MCPError immediately when a misconfigured server returns an unexpected content type (e.g. text/plain) instead of text/event-stream, rather than hanging forever.