Stateful Streamable HTTP: in-session exceptions are masked as an empty -32603; real cause only in a separate "Session crashed" log

[SingingOwl]

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

Summary

In stateful Streamable HTTP (stateless_http=False), when a session's app.run() raises, the client receives JSON-RPC -32603 with the empty message "Error handling POST request: ", and the only prominent server log is anyio.ClosedResourceError. The real exception is logged separately as Session <id> crashed and is never tied to the request — so the actual cause is nearly invisible from the client or a quick log scan.

This is distinct from the DoS crash fixed in 1.10.0 (GHSA-j975-95f5-7wqh): the process stays up. This is the remaining error-propagation / diagnosability gap.

Observed

Repro server is in Example Code below; served via uvicorn repro:app --port 8765 and hit with one initialize POST.

Client response — the real RuntimeError is absent:

HTTP/1.1 500 Internal Server Error
{"jsonrpc":"2.0","id":"server-error","error":{"code":-32603,"message":"Error handling POST request: "}}

Server log — the truth, in a separate task:

Session <id> crashed
  RuntimeError: BOOM-distinctive-root-cause
Error handling POST request
  anyio.ClosedResourceError
Exception in ASGI application
  anyio.ClosedResourceError

(My real-world trigger was OSError: [Errno 24] inotify instance limit reached from a per-session resource; every request then 500'd with an opaque ClosedResourceError, hiding the OSError entirely.)

Root cause

_handle_stateful_request (streamable_http_manager.py) starts run_server (runs app.run() on the session's memory streams), then concurrently calls http_transport.handle_request(). If app.run() raises, run_server logs Session … crashed and connect() tears down the streams. The concurrent _handle_post_request (streamable_http.py) then:

1. raises ClosedResourceError at writer.send(session_message) (session read-stream already closed) — it never sees the real exception, only "stream closed";
2. builds the 500 via _create_error_response(f"Error handling POST request: {err}"), but err is now that ClosedResourceError, whose str() is empty → empty client message;
3. calls writer.send(Exception(err)) into the already-closed stream, raising ClosedResourceError again.

The real exception is decoupled from, and invisible to, the request and the client.

Expected

The client error and/or request-path log should surface the actual exception that crashed the session, not an opaque empty -32603.

Suggested fix

• Capture run_server's exception on the transport and surface it from _handle_post_request.
• Guard the trailing writer.send(Exception(err)) with try/except (ClosedResourceError, BrokenResourceError).
• When str(err) is empty, fall back to repr(err) / the exception type.

Related

• GHSA-j975-95f5-7wqh / Fix uncaught exception in MCP server #967 (1.10.0) fixed the crash, not propagation.
• _handle_stateless_request ClosedResourceError #1219, ClosedResourceError when using FastMCP(..., stateless_http=True, json_response=True) with MCP Inspector #1658 — stateless ClosedResourceError-on-connect.
• Lifespan enters and exits for each request when stateless_http=True #1304 — stateless lifespan-per-request.

This is the stateful error-propagation gap that remains.

Example Code

# Minimal repro — confirmed on mcp 1.27.2 (latest), Python 3.14
# Serve with:  uvicorn repro:app --port 8765
from contextlib import asynccontextmanager
from mcp.server.fastmcp import FastMCP
from mcp.server.transport_security import TransportSecuritySettings

@asynccontextmanager
async def lifespan(server):
    # FastMCP's server lifespan re-enters PER SESSION in stateful mode.
    # Simulate any per-session startup failure:
    raise RuntimeError("BOOM-distinctive-root-cause")
    yield {}

mcp = FastMCP(
    "repro",
    stateless_http=False,
    json_response=True,
    lifespan=lifespan,
    transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),
)

@mcp.tool()
def ping() -> str:
    return "pong"

app = mcp.streamable_http_app()

# Then send one initialize POST (single line):
# curl -s -i -X POST http://127.0.0.1:8765/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}'

Python & MCP Python SDK

Python 3.14 · mcp 1.27.2 (latest) · anyio 4.13 · starlette 1.2.1. (Originally observed on 1.27.1; confirmed identical on 1.27.2.)

[norika1207-lab]

This looks worth pinning down as a protocol-level regression rather than only an implementation bug.

For in-session exceptions masked as empty -32603, the acceptance test I would want is a minimal client/server fixture that records the exact JSON-RPC or HTTP exchange, then asserts both the wire result and the local lifecycle state after the failure path. In MCP deployments, the dangerous failures are often not just wrong return values; they are pending requests, dropped notifications, mismatched session state, or errors that get translated into a generic response and become impossible to diagnose.

A useful fix boundary would preserve three signals: the protocol error sent to the peer, the local exception or cancellation reason available to application code, and a trace/log field that ties the two together. That makes the behavior debuggable for agent hosts without requiring every host to special-case this SDK detail.

[SingingOwl]

Thanks @norika1207-lab — that's a cleaner way to frame it than I did, and I think you're right that the real target is a diagnosability guarantee, which is broader than any single patch.

Against your three signals, here's roughly where @he-yufeng's #2742 sits:

• peer error — covered: _post_error_message now sends the real cause to the client instead of an empty -32603 (with a type-name fallback when str(err) is blank).
• local cause for app code — mostly there server-side (recorded via note_session_run_error and logged), though it's internal rather than something a host can read programmatically, and except Exception would skip cancellation.
• a field tying the two together — the part still open: the 500 and the Session <id> crashed log share an mcp-session-id only implicitly, with no correlator in the error payload.

So #2742 lands the signal that matters most — the peer no longer flies blind — and the other two feel like natural follow-ups rather than blockers. The repro already gives most of the "record the exact exchange" fixture you described; happy to extend it to also assert the post-failure lifecycle state if that'd be useful to anyone.