Title: streamable_http: HTTP status errors (401/403/5xx) on tools/list, tools/call never reach the caller — indistinguishable from a timeout · Issue #3091 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: streamable_http: HTTP status errors (401/403/5xx) on tools/list, tools/call never reach the caller — indistinguishable from a timeout · Issue #3091 · modelcontextprotocol/python-sdk
X Title: streamable_http: HTTP status errors (401/403/5xx) on tools/list, tools/call never reach the caller — indistinguishable from a timeout · Issue #3091 · modelcontextprotocol/python-sdk
Description: Description StreamableHTTPTransport._handle_post_request never notifies the caller of a specific pending request when the server returns a non-2xx status (e.g. 401/403). Instead of surfacing as an error to that request, the caller only e...
Open Graph Description: Description StreamableHTTPTransport._handle_post_request never notifies the caller of a specific pending request when the server returns a non-2xx status (e.g. 401/403). Instead of surfacing as an ...
X Description: Description StreamableHTTPTransport._handle_post_request never notifies the caller of a specific pending request when the server returns a non-2xx status (e.g. 401/403). Instead of surfacing as an ...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/issues/3091
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"streamable_http: HTTP status errors (401/403/5xx) on tools/list, tools/call never reach the caller — indistinguishable from a timeout","articleBody":"## Description\n\n`StreamableHTTPTransport._handle_post_request` never notifies the caller of a specific pending request when the server returns a non-2xx status (e.g. 401/403). Instead of surfacing as an error to that request, the caller only ever observes a read timeout — indistinguishable from a genuinely slow/dead server.\n\n## Root cause (two-level gap)\n\n**1. Missing error path in `_handle_post_request`** (`src/mcp/client/streamable_http.py`):\n\n```python\nasync with ctx.client.stream(\"POST\", self.url, ...) as response:\n if response.status_code == 202:\n ...\n return\n if response.status_code == 404:\n ...\n return\n response.raise_for_status() # \u003c-- no try/except around this\n ...\n```\n\nCompare to its sibling `_handle_json_response` a few lines below, which *does* wrap its work in `try`/`except` and forwards the failure:\n\n```python\nasync def _handle_json_response(self, response, read_stream_writer, is_initialization=False):\n try:\n content = await response.aread()\n message = JSONRPCMessage.model_validate_json(content)\n ...\n await read_stream_writer.send(session_message)\n except Exception as exc:\n logger.exception(\"Error parsing JSON response\")\n await read_stream_writer.send(exc)\n```\n\n`_handle_post_request`'s `raise_for_status()` failure has no equivalent — it propagates out of the fire-and-forget task spawned via `tg.start_soon(handle_request_async)` in `post_writer`, uncaught, with no attempt to notify the specific pending request.\n\n**2. Even the \"obvious\" fix doesn't work, because of how `read_stream` is consumed.** I patched in a `try`/`except httpx.HTTPStatusError` around `raise_for_status()` that forwards the exception via `await ctx.read_stream_writer.send(exc)`, mirroring `_handle_json_response`'s pattern exactly. It made no observable difference to callers.\n\nLooking at `BaseSession._receive_loop` (`src/mcp/shared/session.py`):\n\n```python\nasync for message in self._read_stream:\n if isinstance(message, Exception):\n await self._handle_incoming(message)\n elif isinstance(message.message.root, JSONRPCRequest):\n ...\n elif isinstance(message.message.root, JSONRPCNotification):\n ...\n else: # Response or error\n await self._handle_response(message)\n```\n\nA bare `Exception` on the read stream is routed to `_handle_incoming` — a generic side-channel for unsolicited connection-level issues. Only the `else` branch (`_handle_response`) resolves the specific pending future in `self._response_streams[request_id]` that the original caller is `await`-ing on. Since a bare exception carries no request id, it can never reach `_handle_response`, so the caller's pending request is never resolved by this path either — it can only ever time out.\n\nA real fix needs `_handle_post_request` to construct a proper `JSONRPCError` (carrying the *original request's* id) on an HTTP-status failure and route it through the normal response channel, the same way request-validation failures are already handled inside `BaseSession._receive_loop`:\n\n```python\nerror_response = JSONRPCError(\n jsonrpc=\"2.0\",\n id=message.message.root.id,\n error=ErrorData(code=..., message=..., data=...),\n)\nsession_message = SessionMessage(message=JSONRPCMessage(error_response))\nawait self._write_stream.send(session_message)\n```\n\n## Why it matters\n\nAny client that wants to distinguish \"the server rejected this call\" (e.g. expired/invalid credentials — should fail fast, non-retryable) from \"the server is slow/unreachable\" (should retry) cannot do so over streamable HTTP: both degrade identically as a timeout. We hit this building a Temporal-based SDK that reclassifies MCP failures into a retryable/non-retryable degradation contract — a 401 currently retries `maximum_attempts` times and only then degrades as a *transient* failure, burning retries on what should be an immediate non-retryable auth failure.\n\n## Repro\n\nPoint an `MCPServerStreamableHTTP`/`MCPToolset` client at a server that returns HTTP 401 for `tools/list` or `tools/call`. Observe:\n- No `httpx.HTTPStatusError` (or any status-carrying exception) ever reaches the caller.\n- The caller's `await` only resolves once its own read timeout elapses.\n- The eventual exception (a bare timeout) is indistinguishable from a real 504/slow-server case.\n\n## Environment\n\n- `mcp` 1.25.0 / 1.28.1 (installed via `fastmcp`, which pins `mcp\u003c2.0`)\n- Confirmed via source inspection of `mcp/client/streamable_http.py` and `mcp/shared/session.py`, and via two targeted patch experiments (see root cause above) — not yet checked against the `mcp` 2.0 beta line.\n\nHappy to help test a fix or discuss further.\n","author":{"url":"https://github.com/afterrburn","@type":"Person","name":"afterrburn"},"datePublished":"2026-07-13T19:03:59Z","url":"https://github.com/modelcontextprotocol/python-sdk/issues/3091"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:ad5e31a0-939c-af99-045e-706c1cf93ab4 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | E202:1F7384:11F84D7:17C5C97:6B011747 |
| html-safe-nonce | d839a8cf979c654c2f97b4e82f807d0bace218c6a36387c87845c261a2a6b6cf |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFMjAyOjFGNzM4NDoxMUY4NEQ3OjE3QzVDOTc6NkIwMTE3NDciLCJ2aXNpdG9yX2lkIjoiMjM3MjIxMDM1MzIwMDI0MDQ1NSIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | b2a58490320a8c298e628ff8a545c2956478fff59080c23a00421f98dfcbf86c |
| hovercard-subject-tag | issue:4876745685 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/modelcontextprotocol/python-sdk/3091/issue_layout |
| twitter:image | https://opengraph.githubassets.com/6271ff754d1118824535e58f32504510739a8902ebbfc1001348e39af3d97dac/modelcontextprotocol/python-sdk/issues/3091 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/6271ff754d1118824535e58f32504510739a8902ebbfc1001348e39af3d97dac/modelcontextprotocol/python-sdk/issues/3091 |
| og:image:alt | Description StreamableHTTPTransport._handle_post_request never notifies the caller of a specific pending request when the server returns a non-2xx status (e.g. 401/403). Instead of surfacing as an ... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | afterrburn |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git |
| octolytics-dimension-user_id | 182288589 |
| octolytics-dimension-user_login | modelcontextprotocol |
| octolytics-dimension-repository_id | 862584018 |
| octolytics-dimension-repository_nwo | modelcontextprotocol/python-sdk |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 862584018 |
| octolytics-dimension-repository_network_root_nwo | modelcontextprotocol/python-sdk |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width