streamable_http client call_tool hangs when receiving invalid JSONRPCMessage

[Nuclear2]

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

Issue Description:
During testing, we encountered a critical issue in the Server-Sent Events (SSE) handling mechanism:

1. Problem Trigger:
   To some reason, the _handle_sse_event method received a truncated sse.data payload, causing:
   A JSON parsing exception message = JSONRPCMessage.model_validate_json(sse.data)
   Then the exception handle sent the exc and returned false
2. Current Behavior Gap:
   Despite the failed processing:
   ·No error propagation to the client occurs
   ·No cleanup/retry mechanism is triggered
   ·The client remains stuck in a perpetual wait state for a tool_call result until timeout
3. Critical Impact: The server has already completed the tool_call workflow and moved to the final /done state, creating a state desynchronization between client and server
4. Root Cause Hypothesis:
   It appears that the client failed to detect the reception of invalid responses. The await read_stream_writer.send(exc) did not work during exception handling

Or maybe I missed some configs such as the retry mechanism or other error handling methods?

Example Code

async def _handle_sse_event(
    self,
    sse: ServerSentEvent,
    read_stream_writer: StreamWriter,
    original_request_id: RequestId | None = None,
    resumption_callback: Callable[[str], Awaitable[None]] | None = None,
    is_initialization: bool = False,
) -> bool:
    """Handle an SSE event, returning True if the response is complete."""
    if sse.event == "message":
        try:
            message = JSONRPCMessage.model_validate_json(sse.data) ##### threw the exception
            logger.debug(f"SSE message: {message}")

            # Extract protocol version from initialization response
            if is_initialization:
                self._maybe_extract_protocol_version_from_message(message)

            # If this is a response and we have original_request_id, replace it
            if original_request_id is not None and isinstance(message.root, JSONRPCResponse | JSONRPCError):
                message.root.id = original_request_id

            session_message = SessionMessage(message)
            await read_stream_writer.send(session_message)

            # Call resumption token callback if we have an ID
            if sse.id and resumption_callback:
                await resumption_callback(sse.id)

            # If this is a response or error return True indicating completion
            # Otherwise, return False to continue listening
            return isinstance(message.root, JSONRPCResponse | JSONRPCError)

        except Exception as exc:
            ##### handled exception but client did not receive ######
            logger.exception("Error parsing SSE message")
            await read_stream_writer.send(exc)
            return False
    else:
        logger.warning(f"Unknown SSE event: {sse.event}")
        return False

Python & MCP Python SDK

python == 3.12
SDK == 1.11.0

[astro-angelfish]

To some reason, the _handle_sse_event method received a truncated sse.data payload

This also caused some problem on my side, see jlowin/fastmcp#1152. I did a little investigation and found that character \x85 would lead to the issue. You may also want to check if your mcp tool produces this character, and try to replace that character

The only thing suspicious I found is this, but I didn't get the idea that why other newline character did not trigger the issue.

I've just discovered pydantic won't simply encode special characters as \u0085, instead they used \xc2\x85, which should be encoded in something like utf-8 form. other newline characters like \n are just interpreted as literal \n, a backslash and an n, which will not be truncated by httpx, others like \r are the same too. The pydantic serialization invocation occurred at here, which response is ServerResult, a subtype of RootModel in pydantic, according to this

then the truncation by \x85 occurred at here, breaking the whole json format and causing this issue.

[Nuclear2]

To some reason, the _handle_sse_event method received a truncated sse.data payload

This also caused some problem on my side, see jlowin/fastmcp#1152. I did a little investigation and found that character \x85 would lead to the issue. You may also want to check if your mcp tool produces this character, and try to replace that character

The only thing suspicious I found is this, but I didn't get the idea that why other newline character did not trigger the issue.

I've just discovered pydantic won't simply encode special characters as \u0085, instead they used \xc2\x85, which should be encoded in something like utf-8 form. other newline characters like \n are just interpreted as literal \n, a backslash and an n, which will not be truncated by httpx, others like \r are the same too. The pydantic serialization invocation occurred at here, which response is ServerResult, a subtype of RootModel in pydantic, according to this

then the truncation by \x85 occurred at here, breaking the whole json format and causing this issue.

@astro-angelfish Thanks a lot! Your explanation perfectly aligns with the situation I encountered. It's unfortunate that fixing this requires modifications to low-level SDKs though. On the other hand, I still question whether the current behavior (hang on invalid JSON responses) is actually intentional...

[dbg-raghulkrishna]

I am also facing similar issue. is there any plans to fix this?

[daisyUnicorn]

Waiting for the fix...

[Nuclear2]

@dbg-raghulkrishna @daisyUnicorn I didn't find a solution for the truncation caused by \x85 and other special characters, but I did find a fix for the hang issue.

read_stream_writer.send(exc) sends exceptions to the read_stream, where the _handle_incoming function here (which defaults to no-op) processes them. And this self._handle_incoming is actually calling self._message_handler(req) here which finally comes from ClientSession's init param message_handler above.

So the solution is to add a custom callback that cancels the task group when a validation error occurs. Pass this to the message_handler param in streamable_http's ClientSession. For example:

async def exception_handler(session, exc) #session is your ClientSession yield by streamable_http client
    await anyio.lowlevel.checkpoint()
    if isinstance(exc, ValidationError):
        session._task_group.cancel_scope.cancel()

sess_exception_handler = partial(exception_handler, session = client_session) #client_session is your ClientSession yielded by streamable_http client

Then initialize your ClientSession with:

ClientSession(streams[0], streams[1], message_handler=sess_exception_handler)

Finally, handle the cancellation in your tool call:

try:
    result = await client_session.call_tool(name, kwargs)
except asyncio.CancelledError:
    ### Your custom cleanup/handling here ###

This resolved the hang issue in my case.

[SreehithCoupa]

I am also facing the issue, please fix this at sdk level. And also, it's stuck in the loop and sse session is still continued when we got this issue, atleast I think it should quit the loop.

[ioo0s]

I also encountered the same problem, and it often occurs when using the Tavily tool... Hope this issue can be fixed in the SDK.

[zxkane]

Faced the same behavior when using the streamable HTTP client. The server is hosted on the AWS AgentCore runtime, the server responded with an error message like the one below.

{"jsonrpc":"2.0","error":{"code":-32603,"message":"An internal error occurred while processing the request."},"id":"xxx"}

Some insights from Claude,

Problem Root Cause Identification

  After deep analysis of the MCP SDK source code in the strands virtual environment, I've
  identified the true root cause of why the MCP client hangs when receiving JSON-RPC error
   responses from streamable HTTP servers.

  The Issue is NOT in JSON-RPC Error Parsing

  The MCP SDK correctly handles JSON-RPC error responses at the protocol level. In
  /home/ubuntu/venv/strands/lib/python3.13/site-packages/mcp/shared/session.py:285-286:

  if isinstance(response_or_error, JSONRPCError):
      raise McpError(response_or_error.error)  # ✅ Correctly raises exception

  ★ Insight ─────────────────────────────────────
  Key Finding: JSON-RPC error handling works correctly
  - The MCP SDK properly validates and processes JSON-RPC error responses
  - The send_request method correctly converts JSON-RPC errors to McpError exceptions
  - The hanging occurs at a lower level in the HTTP transport layer
  ─────────────────────────────────────────────────

  Actual Root Cause: HTTP Streaming Layer Deadlock

  1. The Problem Location

  The hang occurs in /home/ubuntu/venv/strands/lib/python3.13/site-packages/mcp/client/str
  eamable_http.py:302:

  async def _handle_json_response(self, response, read_stream_writer, 
  is_initialization=False):
      try:
          content = await response.aread()  # ⚠️ THIS LINE HANGS
          message = JSONRPCMessage.model_validate_json(content)
          # ... rest of processing

  2. HTTP Stream Context Issue

  The streamable HTTP implementation uses httpx.stream() context manager:

  async with ctx.client.stream("POST", self.url, json=...) as response:
      # ... process response
      content_type = response.headers.get(CONTENT_TYPE, "").lower()
      if content_type.startswith(JSON):
          await self._handle_json_response(response, ctx.read_stream_writer,
  is_initialization)

  3. Why response.aread() Hangs

  When a server returns a JSON-RPC error response:

  1. HTTP Level: Response headers and status are received correctly (as shown in your
  logs)
  2. Stream Level: The HTTP response stream may not be properly closed by the server
  3. Client Level: response.aread() waits indefinitely for more data that never comes
  4. Result: The MCP client hangs waiting for stream completion

  Evidence from Your Logs

  Your debug logs confirm this analysis:

  2025-09-03 20:52:43,071 | DEBUG | httpcore.http11 | receive_response_body.complete
  2025-09-03 20:52:43,071 | DEBUG | httpcore.http11 | response_closed.complete  
  2025-09-03 20:52:43,071 | DEBUG | mcp.http.detailed | 📦 Response Body (JSON):
  {
    "jsonrpc": "2.0",
    "error": {
      "code": -32603,
      "message": "An internal error occurred while processing the request."
    }
  }

[tanhaipeng]

I encountered the same problem. When the returned result contains special characters (such as \x85), the client will hang.
The current imperfect solution is to register a message_handler, raise an exception in it, and capture it at the upper layer.
This bug needs to be fixed with high priority by the official.

[tauzhang-cn]

2025-09-25 21:32:08 - ERROR - [sse.py:109] - Error in sse_reader
Traceback (most recent call last):
  File "/Users/tau/PycharmProjects/agent-center/chat_agent/.venv/lib/python3.13/site-packages/mcp/client/sse.py", line 72, in sse_reader
    async for sse in event_source.aiter_sse():
    ...<34 lines>...
                logger.warning(f"Unknown SSE event: {sse.event}")
  File "/Users/tau/PycharmProjects/agent-center/chat_agent/.venv/lib/python3.13/site-packages/httpx_sse/_api.py", line 37, in aiter_sse
    self._check_content_type()
    ~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/tau/PycharmProjects/agent-center/chat_agent/.venv/lib/python3.13/site-packages/httpx_sse/_api.py", line 18, in _check_content_type
    raise SSEError(
    ...<2 lines>...
    )
httpx_sse._exceptions.SSEError: Expected response header Content-Type to contain 'text/event-stream', got ''

SDK will skip this exception instead of reRaise it, and it causes that my sse connection will not be stopped. This bug needs to be fixed with high priority by the official.