[tadasant]

Disclosure: This is a first-pass, agent-driven contribution. Implementation, tests, and initial review were performed with AI agents; this draft needs human maintainer review before it is considered ready to merge.

Problem

A 401 or 403 that carries no WWW-Authenticate challenge did not keep a structured HTTP status in the reqwest Streamable HTTP client:

• POST read the whole response body, then returned UnexpectedServerResponse("HTTP 401 Unauthorized: <body>"). Callers had to parse the string, the body was retained in the error, and an unfinished body blocked the request even though the status alone already settled it.
• GET returned the backend's reqwest::Error from error_for_status(), so callers had to depend on the backend type.

A 401/403 with a challenge was already returned without reading the body (AuthRequired / InsufficientScope), as was a 429 (HttpStatusError).

Changes

• Challenge-less 401 and 403 are classified as the existing body-free HttpStatusError on GET and POST, without reading the body, including when the body is a JSON-RPC error. 401/403 with a challenge keep their AuthRequired / InsufficientScope precedence. 404 session expiry, non-auth JSON-RPC error bodies, the sessionless discover fallback, 429 and 5xx handling are unchanged.
• The metadata is reachable without naming the transport type: StreamableHttpError::HttpStatus now exposes the HttpStatusError as its source() (Display is unchanged, HTTP 401), and ClientInitializeError::TransportError, ServerInitializeError::TransportError and ServiceError::TransportSend expose their DynamicTransportError as source(). Walking ClientInitializeError → DynamicTransportError → StreamableHttpError → HttpStatusError finds it, at initialization and at runtime.
• ClientInitializeError::is_authorization_required() is also true for a challenge-less 401, since the request lacked valid credentials and the MCP spec has discovery fall back to the well-known URIs when no resource_metadata is advertised. auth_challenge() stays None for it. A challenge-less 403 is not classified as authorization required.

Before / after on the wire

Reproduction: a minimal MCP server (rmcp's own Streamable HTTP server behind a token gate) and a client probe that prints what the SDK hands back, committed on this fork at tadasant/rust-sdk@5b3f78a (README). It is not a workspace member and depends on ../crates/rmcp by path, so the same binaries run against any checkout. Captured output: before, upstream main c164688 · after, this PR 109d574. Ports and the worker type path are elided below.

Scenarios no-challenge and no-challenge-unfinished-body. The server answers an unauthenticated request with 401 and an under-scoped one with 403, no WWW-Authenticate field, Content-Type: application/json and a JSON-RPC error body; in the second scenario the body never finishes.

Before (upstream main):

sequenceDiagram
    participant C as rmcp client
    participant S as MCP server
    C->>S: POST /mcp initialize (no token)
    S-->>C: 401, no WWW-Authenticate<br/>Content-Type: application/json<br/>{"jsonrpc":"2.0","id":1,"error":{…}}
    Note over C: no challenge, so the response falls through to the body path
    C->>S: reads the whole body
    Note over C: blocks for as long as the server keeps the body open
    C->>C: UnexpectedServerResponse("HTTP 401 Unauthorized: {…body…}")
    Note over C: is_authorization_required() = false, auth_challenge() = None<br/>body retained in the error
    C->>S: GET /mcp (no token)
    S-->>C: 401, no WWW-Authenticate
    C->>C: Client(reqwest::Error "HTTP status client error (401 Unauthorized) for url …")
    Note over C: a different, backend-typed error for the same condition

Loading

After (this PR):

sequenceDiagram
    participant C as rmcp client
    participant S as MCP server
    C->>S: POST /mcp initialize (no token)
    S-->>C: 401, no WWW-Authenticate<br/>Content-Type: application/json<br/>{"jsonrpc":"2.0","id":1,"error":{…}}
    Note over C: the status settles it, the body is not read
    C->>C: HttpStatus { status: 401, retry_after: None }
    Note over C: is_authorization_required() = true, auth_challenge() = None
    C->>S: GET /mcp (no token)
    S-->>C: 401, no WWW-Authenticate
    C->>C: HttpStatus { status: 401, retry_after: None }
    Note over C: same typed error on both methods, reachable through source()
    C->>S: GET /.well-known/oauth-protected-resource/mcp (well-known fallback, MCP spec)

Loading

Probe	upstream main (c164688)	this PR (109d574)
no-challenge, initialize with no token	Err(Send message error Transport […] error: unexpected server response: HTTP 401 Unauthorized: {"jsonrpc":"2.0","id":1,"error":{"code":-32001,"message":"Unauthorized"}}, when send initialize request)	Err(Send message error Transport […] error: HTTP 401, when send initialize request)
… → is_authorization_required() / auth_challenge()	false / None	true / None
no-challenge, POST with no token	UnexpectedServerResponse("HTTP 401 Unauthorized: {…body…}")	HttpStatus { status: 401, retry_after: None }
no-challenge, GET with no token	Client(reqwest: HTTP status client error (401 Unauthorized) for url (…))	HttpStatus { status: 401, retry_after: None }
no-challenge, POST / GET with under-scoped token	UnexpectedServerResponse("HTTP 403 Forbidden: {…body…}") / Client(reqwest: … 403 Forbidden …)	HttpStatus { status: 403, retry_after: None } on both
no-challenge-unfinished-body, initialize and POST	still waiting / still reading the body after 3 s	HttpStatus { status: 401 } immediately (403 with the under-scoped token)
no-challenge-unfinished-body, GET	Client(reqwest: … 401 …) (status known, body not read)	HttpStatus { status: 401, retry_after: None }

Unchanged in both revisions: the basic-then-bearer and quoted-text scenarios (the subject of #1418) behave the same with and without this PR.

How the fix maps to the specs

Spec says	Code now does	Test
MCP Error Handling: "Servers MUST return appropriate HTTP status codes for authorization errors: 401 Unauthorized — Authorization required or token invalid; 403 Forbidden — Invalid scopes or insufficient permissions" (2025-11-25, 2026-07-28) and Token Handling: "Invalid or expired tokens MUST receive a HTTP 401 response."	The status code is the normative signal, so it is what the client keeps: HttpStatusError { status: 401 | 403, retry_after }, the same typed shape on GET and POST, reachable through the error's source chain at initialization and at runtime.	tests/test_streamable_http_status_metadata.rs::challenge_less_auth_failures_return_body_free_metadata (401/403 × GET/POST × JSON/text body × finished/unfinished), test_streamable_http_4xx_error_body.rs::http_40{1,3}_json_rpc_error_body_without_challenge_keeps_status, test_streamable_http_get_stream_auth_challenge.rs::get_stream_auth_failure_without_challenge_keeps_status, test_auth_error_classification.rs::http_status_remains_available_as_an_error_source
RFC 9110 §15.5.2: "The 401 (Unauthorized) status code indicates that the request has not been applied because it lacks valid authentication credentials for the target resource. The server generating a 401 response MUST send a WWW-Authenticate header field (Section 11.6.1) containing at least one challenge applicable to the target resource." (link)	A challenge-less 401 is a server-side violation of this MUST, but its meaning is still "lacks valid credentials", so is_authorization_required() reports it. With no challenge there is nothing for auth_challenge() to return.	test_auth_error_classification.rs::classifies_challenge_less_http_401_only; auto_discovery_preserves_metadata_without_legacy_fallback asserts is_authorization_required() == (status == 401) and auth_challenge() == None
MCP Protected Resource Metadata Discovery Requirements: "MCP clients MUST support both discovery mechanisms and use the resource metadata URL from the parsed WWW-Authenticate headers when present; otherwise, they MUST fall back to constructing and requesting the well-known URIs in the order listed above." (2025-11-25, 2026-07-28); the discovery sequence diagram labels the response "HTTP 401 Unauthorized (may include WWW-Authenticate header)".	This is why a challenge-less 401 is actionable rather than a dead end: an application that sees is_authorization_required() can start AuthorizationRequest without with_challenge, and the SDK's existing resolve_metadata_from_challenge(None) path performs the well-known fallback.	classifies_challenge_less_http_401_only (classification); the fallback itself is existing, already-tested behaviour and is not changed here.
RFC 9110 §15.5.4: "The 403 (Forbidden) status code indicates that the server understood the request but refuses to fulfill it. … The client SHOULD NOT automatically repeat the request with the same credentials. … However, a request might be forbidden for reasons unrelated to the credentials." (link)	A challenge-less 403 keeps its status but is not classified as authorization required or insufficient scope: without error="insufficient_scope" there is no step-up to run, and the refusal may be unrelated to credentials.	classifies_challenge_less_http_401_only (403 branch), auto_discovery_preserves_metadata_without_legacy_fallback::forbidden
RFC 6750 §3: "If the protected resource request does not include authentication credentials or does not contain an access token that enables access to the protected resource, the resource server MUST include the HTTP "WWW-Authenticate" response header field" (link); MCP Runtime Insufficient Scope Errors: "the server SHOULD respond with: HTTP 403 Forbidden … WWW-Authenticate header with the Bearer scheme and additional parameters: error="insufficient_scope" … scope=…" (2025-11-25)	When the challenge is present, the specialised errors still win over status metadata, and they too return before the body finishes. The challenge, not the body, carries the actionable information.	auth_challenges_take_precedence_over_status_metadata (401/403 × GET/POST, unfinished JSON body)
MCP sequence diagram, no resource_metadata: "Abort or use pre-configured values" after the well-known probes fail; nothing in the MCP spec or the RFCs specifies what a client should surface for a 401/403 that has no challenge.	Spec is silent here. Returning body-free HttpStatusError is the SDK's own design choice, consistent with #1386 ("No response body, request URL, credentials, or other headers are retained") and with #1341 (keep the HTTP status rather than pass a 401 body off as an ordinary JSON-RPC error). The trade-off is that a human-readable message in the body is no longer in the error; the status and Retry-After are.	challenge_less_auth_failures_return_body_free_metadata and assert_status_error check the error renders no body, URL, session or token (private-* markers).

Relationship to #1418

#1418 (preserve repeated WWW-Authenticate fields) touches the same 401/403 region of transport/common/reqwest/streamable_http_client.rs. The two are independent: #1418 replaces the challenge-present branches with a shared auth_challenge_error helper, this PR changes http_status_error and the POST body path below them. Whichever lands second needs a small rebase. Together they give: challenge present → AuthRequired / InsufficientScope carrying every field; no challenge → HttpStatus.

Compatibility

• StreamableHttpError is #[non_exhaustive]. Callers that matched UnexpectedServerResponse (POST) or Client(_) (GET) for a challenge-less 401/403 now receive HttpStatus; this is the intended behaviour change. The SemVer and Public API CI jobs pass without a breaking-change marker.
• StreamableHttpError::HttpStatus keeps its Display (HTTP 503) but now has a source(); ClientInitializeError::TransportError, ServerInitializeError::TransportError and ServiceError::TransportSend now have a source(). All are additive for error-chain walkers. A "caused by" printer will show HTTP 503 twice in a row (variant, then HttpStatusError), the same pattern the enum's other #[from] variants and DynamicTransportError already produce.
• is_authorization_required() is documented (code and docs/OAUTH_SUPPORT.md) to also cover a challenge-less 401.

Validation

Run locally on Rust 1.96 (the pinned toolchain) with the commands CI uses:

• cargo clippy --all-targets --all-features -- -D warnings
• cargo clippy -p rmcp --lib --no-default-features --features <f> -- -D warnings for client, auth, transport-streamable-http-client, transport-streamable-http-client-reqwest, and no features
• cargo test -p rmcp --features client,server,auth,transport-streamable-http-client-reqwest,transport-streamable-http-client-unix-socket --lib --test test_streamable_http_get_stream_auth_challenge --test test_streamable_http_status_metadata --test test_streamable_http_4xx_error_body --test test_auth_error_classification --test test_streamable_http_reconnect_classification
• cargo +nightly fmt --all -- --check, typos, git diff --check

On unmodified main, the two …without_challenge_keeps_status tests fail with UnexpectedServerResponse("HTTP 401 Unauthorized: {…}"), which confirms the body-containing string error.

Scope / review notes

• Reqwest GET/POST only. DELETE and the Unix socket backend are unchanged; the Unix socket client still reads the body and returns UnexpectedServerResponse for a challenge-less 401/403 (and for 429/5xx), so is_authorization_required() stays false for it. HttpStatusError's docs scope the behaviour to the reqwest client.
• AuthClient still refreshes a token only on AuthRequired; a challenge-less 401 propagates without a silent refresh, as before.
• No legacy SSE transport or protocol negotiation changes.

Noticed, not filed

• classify_reconnect_error treats a challenge-less 401/403 on the GET stream as retryable (it did before too, as a Client error); repeating the GET with the same credentials cannot help.

🤖 Generated with Claude Code

[github-actions]

@gocamille is on triage rotation this week and is the reviewer for this one.

Labels come from the PR labeler. Please review the change.

_{Automated triage. Labels are a first pass and the assigned maintainer has the final say.}

[WeekendSuperhero]

This would also fix a regression we hit after moving to 3.9.0. Could the same approach cover one more case?

3.9.0 drops the status of an oversized 4xx. The RUSTSEC-2026-0462 fix bounds a non-success POST body to MAX_ERROR_RESPONSE_SIZE (64 KiB). Past that limit, a status-bearing error is returned only when http_status_error produces one, which is only for 429 and 5xx. Every other status comes back as ResponseBodyTooLarge { max_size }, and the status is lost. We see this in two places:

1. A challenge-less 401 with a large body, typically an SSO login page served as HTML. In 3.8.0 this arrived as UnexpectedServerResponse("HTTP 401 …"), so refresh-on-401 logic could act on it. In 3.9.0 it is indistinguishable from any other oversized reply. This PR fixes that case, because a challenge-less 401/403 is classified before the body is read. Thank you.
2. A legacy server that rejects server/discover with a 400, 404 or 405 and a large body (an HTML error page). The client can no longer tell that this is a rejection, so a client in Auto mode can't recognise the server as one that doesn't support 2026-07-28 and probes it again on every connect.

Request: when a non-success body exceeds the limit, could the error carry the status for every status, not only 429/5xx? For example, return HttpStatusError for any non-success status on that path, or add status to ResponseBodyTooLarge. The body would still never be buffered past the limit, so the advisory fix is unaffected.

Happy to open a separate issue if you'd rather keep this PR scoped to 401/403.