fix(client): propagate HTTP transport errors to caller (#2110)

[fede-kamel]

Summary

Fix for #2110: in sse_client and streamable_http_client, HTTP and network errors during POST were caught by a bare except Exception and only logged — callers blocked forever on read_stream.receive() because the failure was never delivered through the stream.

This PR:

• Moves the error handling inside _send_message (SSE) and handle_request_async (StreamableHTTP) so exceptions are caught before anyio's task group wraps them in a BaseExceptionGroup. A narrow except httpx.HTTPError forwards the exception to read_stream_writer, mirroring the pattern already used by stdio.py and websocket.py.
• Preserves the upstream HTTP status code in ErrorData.data = {"http_status": N} for both the 404 session-terminated branch and the generic ≥400 branch in _handle_post_request, and includes the status in error.message for the generic branch. JSON-RPC code mapping is unchanged.

Status: draft — awaiting ready for work label on #2110 per CONTRIBUTING.md. Code is verified locally; opening as draft so review can start when maintainers are ready. Happy to close and wait if you'd prefer.

Test plan

Unit (httpx.MockTransport, fast / deterministic)

• test_sse_client_propagates_post_http_error_to_caller[401|404|500] — parametrized over three status codes. Uses a _LongLivedSSEStream helper to emit the endpoint event and keep the SSE GET open (mirrors real server behaviour so sse_reader doesn't tear down the stream before the POST path runs).
• test_streamable_http_client_propagates_post_network_error_to_caller — MockTransport handler raises httpx.ConnectError, asserts the exception surfaces on read_stream.

Integration (real uvicorn subprocess)

• test_sse_client_real_server_surfaces_post_http_error[401|404|500] — real SseServerTransport on GET /sse, custom Route on POST /messages/ returning the configured status. Real httpx client against 127.0.0.1:<ephemeral>. Asserts real httpx.HTTPStatusError.response.status_code surfaces via read_stream within fail_after(5).
• test_sse_client_real_server_handles_no_route_match — server has NO /messages/ POST route (starlette emits a natural 404). Distinct from the deliberate-status case.
• test_streamable_http_client_real_server_preserves_http_status[500|401|404] — real uvicorn /mcp returning the configured status. Asserts:
  • correct JSON-RPC error.code mapping (500/401 → INTERNAL_ERROR, 404 → INVALID_REQUEST "Session terminated")
  • error.data == {"http_status": <N>} (the newly-preserved HTTP status)
  • the status code appears in error.message for non-404 cases.
• test_streamable_http_client_real_server_surfaces_network_error — binds an ephemeral port, never starts a server on it. Real httpx.ConnectError arrives on read stream (not a hang).

Negative control (proof of regression guard)

I reverted the fix with git stash push src/mcp/client/sse.py src/mcp/client/streamable_http.py and re-ran all 10 substantive test cases. All 10 failed against unfixed main — the pre-fix code hit every fail_after(3) / fail_after(5) deadline waiting for a response that never arrived. With the fix restored, all 10 pass. Before/after logs available on request.

Local CI equivalent

$ ./scripts/test
...
1180 passed, 98 skipped, 1 xfailed in ~20s
TOTAL   19845   0   1506   0  100.00%
✅ No lines wrongly marked with 'pragma: no cover'

Plus ruff check, ruff format, pyright, and pre-commit on the changed files — all clean.

Scope deliberately excluded

• Introduce typed error classes with metadata #1742 typed error hierarchy — separate issue, would expand this PR's scope.
• Transport-level heartbeat / liveness detection — orthogonal; worth discussing in a follow-up issue.
• test_stdio.py flaky test (the thing that sank PR fix(client): propagate HTTP transport exceptions to caller #2124) — not touched here. Out of scope.
• Session-scoped tests at the ClientSession level — happy to add in this PR or a follow-up if preferred; transport-level coverage is already thorough.

Relationship to prior PRs

• fix(client): propagate HTTP transport exceptions to caller #2124 (still open, stale since 2026-03-05) — fresh branch without the scope creep that seems to have stalled it. If you'd prefer I coordinate with @gspeter-max to rebase/carry their commits, say the word.
• fix: preserve HTTP status code in streamable HTTP client error messages #2173, fix: preserve HTTP status codes in streamable HTTP transport error responses #2176, fix: propagate HTTP errors from transports instead of silently logging #2249, Handle connection errors in StreamableHTTP post_writer #2282 — closed unmerged. My approach differs by (a) catching HTTPError inside the inner task function so anyio's BaseExceptionGroup wrapping doesn't swallow it, and (b) preserving HTTP status in ErrorData.data rather than via a new exception type (minimal, non-breaking).

Closes #2110 (if scope is accepted — happy to remove this line).