[Moonelos]

Related to #3560 (the HTTP ReadTimeout case). This does not fix every transport error in that issue.

Contain an HTTP read timeout in its request task and return a correlated REQUEST_TIMEOUT (-32001), so one slow POST does not cancel sibling requests or tear down the shared session.

Motivation and Context

With the current streamable HTTP transport, httpx2.ReadTimeout while awaiting POST response headers or reading a JSON response escapes into the shared AnyIO task group. Other in-flight calls are cancelled and transport cleanup raises an ExceptionGroup. This was observed downstream with MCP 2.3.0, FastMCP 4.1.1 and Cortex; the SDK-only regression tests reproduce it on main at 2af9e30.

The fix catches only ReadTimeout, resolves the original request through the existing response channel, and uses a fixed message rather than forwarding upstream exception details. No retry is added. Initial initialize/server-discover errors and explicit cancellation retain their existing behavior. Notification failures and other transport exception types remain outside this patch's scope.

This overlaps the ReadTimeout portion of #3584, which is closed and unmerged. This narrower patch uses REQUEST_TIMEOUT and also covers resumption-header timeouts.

How Has This Been Tested?

• New regression scenarios cover response-header and JSON-body timeouts under legacy and 2026-07-28 protocols. Each keeps a sibling request in flight until the timeout reaches its caller, then verifies the sibling and a subsequent request succeed, with one submission per tool and a closed failed response body.
• Resumption GET timeout retains the original request ID and does not submit a POST retry.
• Handshake ReadTimeout remains a raw transport failure without starting a fallback handshake.
• A pinned-gap test records that a failed notification still ends the POST writer.
• All four primary scenarios fail against unpatched main with an escaping ReadTimeout.

Final validation (Python 3.12.15, upstream frozen lockfile):

• ./scripts/test — 6,220 passed, 10 skipped, 1 xfailed; 100% branch coverage; strict-no-cover passed.
• uv run --frozen ruff check . and formatting checks on changed Python files — passed.
• uv run --frozen pyright src/mcp/client/streamable_http.py tests/client/test_streamable_http.py — 0 errors.
• Full uv run --frozen pyright reports two macOS os.waitid errors in unchanged tests/transports/stdio/test_lifecycle.py:190; no errors in changed files.
• Downstream FastMCP/Cortex integration was not rerun for this upstream patch; those versions supplied the original report.

Breaking Changes

A request-local HTTP ReadTimeout now reaches its caller as MCPError(REQUEST_TIMEOUT), rather than cancelling the surrounding task group and surfacing during transport cleanup. No public signatures or configuration change. Server execution may continue after the client's timeout; this fix does not make retrying mutating calls safe.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I am assigned to the linked issue (or it is labeled help wanted, or I'm a maintainer)
• I have disclosed any AI assistance and can explain the change in my own words — AI assistance is disclosed below; human review is pending.
• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

AI disclosure: Codex prepared the implementation, regression tests, and this description from the reporter's local patch and investigation. This draft awaits human review; it does not claim the author has reviewed or can personally explain all generated changes.

The linked issue has not been assigned to this author. This PR covers only its ReadTimeout case and deliberately uses a non-closing reference. Under the repository's intake policy, it may be automatically closed until a maintainer accepts and assigns the work.

[github-actions]

This PR has been closed automatically. It's still a draft, but we close those early so you don't put in more time only to have it closed the moment you mark it ready.

This repo only keeps pull requests open when they come from a maintainer, or from a contributor a maintainer has assigned to the linked issue, and this PR doesn't link an open issue yet.

• If you're already assigned to an issue for this, add Fixes #<n> to the description and the PR will reopen on its own.
• If there's no issue yet, please open one instead: what you ran into, why it matters for your use case, and a minimal reproduction. That context is super important to us and is what we use to decide what to prioritise.
• If there's an issue but you're not assigned, add Fixes #<n> anyway so they're linked, then engage on the issue itself by confirming the repro or describing the approach you'd take. Assignment is a maintainer call based on capacity; comments that only ask to be assigned don't factor in. If you are assigned, this PR reopens automatically.

You're welcome to keep pushing commits here (just avoid force-pushing, since GitHub can't reopen a rewritten branch), but that on its own won't get the PR reviewed or the issue assigned, and realistically most auto-closed PRs stay closed. There's no need to open a new PR either way.

CONTRIBUTING.md has the full reasoning, but in short:

• We're a small team with very little capacity to review community PRs right now.
• Many recent PRs are AI-generated with little human review, and reviewing one carefully still costs a maintainer as much time as it ever did. A well-described issue is usually more useful to us than the code.

Maintainers: reopen, remove missing-issue-link, or add bypass-issue-check to override.