feat: classify authorization-required errors

Author: DaleSeo

crates/rmcp/Cargo.toml

@@ -385,6 +385,11 @@ name = "test_client_credentials"
 required-features = ["auth"]
 path = "tests/test_client_credentials.rs"
 
+[[test]]
+name = "test_auth_error_classification"
+required-features = ["auth", "client", "transport-streamable-http-client"]
+path = "tests/test_auth_error_classification.rs"
+
 [[test]]
 name = "test_unix_socket_transport"
 required-features = [

crates/rmcp/src/service/client.rs

@@ -111,6 +111,17 @@ impl ClientInitializeError {
         }
         None
     }
+
+    /// Returns whether client initialization failed because authorization is required.
+    ///
+    /// This covers both missing or expired local OAuth authorization and an HTTP
+    /// authorization challenge from the MCP server.
+    pub fn is_authorization_required(&self) -> bool {
+        matches!(
+            self,
+            Self::TransportError { error, .. } if error.is_authorization_required()
+        )
+    }
 }
 
 /// Helper function to get the next message from the stream

crates/rmcp/src/transport.rs

@@ -272,6 +272,27 @@ impl DynamicTransportError {
         }
     }
 
+    pub(crate) fn is_authorization_required(&self) -> bool {
+        let mut error = Some(self.error.as_ref() as &(dyn std::error::Error + 'static));
+        while let Some(current) = error {
+            #[cfg(feature = "auth")]
+            if matches!(
+                current.downcast_ref::<auth::AuthError>(),
+                Some(auth::AuthError::AuthorizationRequired)
+            ) {
+                return true;
+            }
+
+            #[cfg(feature = "transport-streamable-http-client")]
+            if current.is::<streamable_http_client::AuthRequiredError>() {
+                return true;
+            }
+
+            error = current.source();
+        }
+        false
+    }
+
     pub fn downcast<T: Transport<R> + 'static, R: ServiceRole>(self) -> Result<T::Error, Self> {
         if !self.is::<T, R>() {
             Err(self)

crates/rmcp/tests/test_auth_error_classification.rs

@@ -0,0 +1,85 @@
+use std::{any::TypeId, error::Error};
+
+use rmcp::{
+    service::ClientInitializeError,
+    transport::{
+        AuthError, DynamicTransportError,
+        streamable_http_client::{AuthRequiredError, InsufficientScopeError, StreamableHttpError},
+    },
+};
+use thiserror::Error;
+
+type TestHttpError = StreamableHttpError<std::io::Error>;
+
+#[derive(Debug, Error)]
+#[error("outer transport wrapper")]
+struct OuterError(#[source] TestHttpError);
+
+fn initialization_error(error: impl Error + Send + Sync + 'static) -> ClientInitializeError {
+    ClientInitializeError::TransportError {
+        error: DynamicTransportError::from_parts(
+            "test transport",
+            TypeId::of::<()>(),
+            Box::new(error),
+        ),
+        context: "initialize".into(),
+    }
+}
+
+#[test]
+fn classifies_local_authorization_required() {
+    let error = TestHttpError::Auth(AuthError::AuthorizationRequired);
+
+    assert!(initialization_error(error).is_authorization_required());
+}
+
+#[test]
+fn classifies_http_authorization_challenge() {
+    let error =
+        TestHttpError::AuthRequired(AuthRequiredError::new("Bearer realm=\"mcp\"".to_owned()));
+
+    assert!(initialization_error(error).is_authorization_required());
+}
+
+#[test]
+fn classifies_authorization_required_through_multiple_sources() {
+    let error = OuterError(TestHttpError::Auth(AuthError::AuthorizationRequired));
+
+    assert!(initialization_error(error).is_authorization_required());
+}
+
+#[test]
+fn does_not_classify_unrelated_transport_errors() {
+    let closed = TestHttpError::TransportChannelClosed;
+    let refresh = TestHttpError::Auth(AuthError::TokenRefreshFailed("timeout".to_owned()));
+    let scope = TestHttpError::InsufficientScope(InsufficientScopeError::new(
+        "Bearer error=\"insufficient_scope\"".to_owned(),
+        Some("admin".to_owned()),
+    ));
+
+    assert!(!initialization_error(closed).is_authorization_required());
+    assert!(!initialization_error(refresh).is_authorization_required());
+    assert!(!initialization_error(scope).is_authorization_required());
+}
+
+#[test]
+fn does_not_classify_non_transport_initialization_errors() {
+    assert!(!ClientInitializeError::Cancelled.is_authorization_required());
+    assert!(
+        !ClientInitializeError::ConnectionClosed("server closed the connection".to_owned())
+            .is_authorization_required()
+    );
+}
+
+#[test]
+fn http_challenge_remains_available_as_an_error_source() {
+    let error =
+        TestHttpError::AuthRequired(AuthRequiredError::new("Bearer realm=\"mcp\"".to_owned()));
+
+    let source = error.source().expect("auth challenge should be a source");
+    let challenge = source
+        .downcast_ref::<AuthRequiredError>()
+        .expect("source should retain the challenge type");
+
+    assert_eq!(challenge.www_authenticate_header, "Bearer realm=\"mcp\"");
+}

docs/OAUTH_SUPPORT.md

@@ -254,6 +254,26 @@ let client_service = ClientInfo::default();
 let client = client_service.serve(transport).await?;
 ```
 
+If initialization reports that authorization is required, return to the
+application's authorization flow:
+
+```rust ignore
+let client = match client_service.serve(transport).await {
+    Ok(client) => client,
+    Err(error) if error.is_authorization_required() => {
+        // Prompt the user and start the application's authorization flow again.
+        return Err(error.into());
+    }
+    Err(error) => return Err(error.into()),
+};
+```
+
+The predicate covers both missing or expired local OAuth authorization and an
+HTTP 401 challenge from the MCP server. Other failures, including transient
+token-refresh errors and insufficient scope, return `false`. The original error
+is preserved for logging or more detailed handling; the SDK does not start an
+authorization flow automatically.
+
 ### 6. Handle scope upgrades
 
 If a server returns 403 with `insufficient_scope`, you can request a scope

docs/plans/2026-07-27-issue-795-auth-error-classification.md

@@ -0,0 +1,159 @@
+# Plan: Classify authorization-required initialization errors
+
+**Date:** 2026-07-27
+**Issue:** [#795](https://github.com/modelcontextprotocol/rust-sdk/issues/795)
+**Goal:** Let clients detect that MCP initialization requires re-authorization without downcasting a transport-specific error or matching multiple internal variants. Preserve the existing error details and `WWW-Authenticate` challenge.
+**Status:** Complete
+
+## Context
+
+An authorized streamable HTTP client can currently report the same caller action—start authorization again—through two different paths:
+
+- `StreamableHttpError::Auth(AuthError::AuthorizationRequired)` when the local OAuth manager has no usable credentials or cannot refresh them.
+- `StreamableHttpError::AuthRequired(AuthRequiredError)` when the MCP endpoint returns an HTTP 401 challenge.
+
+`ClientInitializeError` erases the concrete transport error into `DynamicTransportError`. Callers must therefore know the HTTP client's concrete error type, downcast it, and match both variants.
+
+The variants should remain distinct internally. The HTTP form carries a `WWW-Authenticate` header, while the OAuth-manager form describes local credential state and is only available with the `auth` feature. Merging them would either lose challenge data or make the streamable HTTP transport depend on OAuth even when OAuth support is disabled.
+
+The public API addition is:
+
+```rust
+impl ClientInitializeError {
+    pub fn is_authorization_required(&self) -> bool;
+}
+```
+
+Internally, `DynamicTransportError` inspects the standard `std::error::Error::source` chain. `ClientInitializeError` delegates for its `TransportError` variant and returns `false` for all other variants. The transport-level helper remains crate-internal until another public use case requires it.
+
+`AuthRequiredError` must participate in that source chain. It should implement `std::error::Error`, and `StreamableHttpError::AuthRequired` should expose it as its source. `StreamableHttpError::Auth(AuthError)` already exposes `AuthError` through `thiserror`.
+
+## Scope
+
+- Detect both authorization-required paths through one public predicate.
+- Work for direct and wrapped transport errors without requiring the caller to name the HTTP backend's error type.
+- Preserve existing public variants and challenge data.
+- Document the re-authorization pattern.
+
+## Non-goals
+
+- Do not merge or remove `AuthError::AuthorizationRequired` and `StreamableHttpError::AuthRequired`.
+- Do not classify `InsufficientScope`, transient refresh failures, session expiry, or arbitrary HTTP failures as authorization-required.
+- Do not automatically start an OAuth flow.
+- Do not add a generalized error-category framework or change the `Transport` trait.
+- Do not add the predicate to `RmcpError` until a caller demonstrates that the broader wrapper needs it.
+
+## File Map
+
+| File | Role | Status |
+| --- | --- | --- |
+| `crates/rmcp/src/transport/streamable_http_client.rs` | Verify the HTTP 401 detail error is visible through the standard source chain | Complete upstream |
+| `crates/rmcp/src/transport.rs` | Add transport-independent authorization-required classification | Complete |
+| `crates/rmcp/src/service/client.rs` | Add the initialization-error convenience predicate | Complete |
+| `crates/rmcp/tests/test_auth_error_classification.rs` | Exercise the public API and guard false positives | Complete |
+| `crates/rmcp/Cargo.toml` | Declare the feature-gated integration test | Complete |
+| `docs/OAUTH_SUPPORT.md` | Show callers how to branch back into authorization | Complete |
+
+## Tasks
+
+### 1. Add public-API regression tests
+
+**Files:** `crates/rmcp/tests/test_auth_error_classification.rs`, `crates/rmcp/Cargo.toml`
+
+**Description:** Add a feature-gated integration test that constructs public error values through `DynamicTransportError::from_parts` and verifies the intended classification before implementation.
+
+**Acceptance criteria:**
+
+- [x] `StreamableHttpError::Auth(AuthError::AuthorizationRequired)` classifies as authorization-required.
+- [x] `StreamableHttpError::AuthRequired(AuthRequiredError)` classifies as authorization-required.
+- [x] A `ClientInitializeError::TransportError` wrapping either path classifies as authorization-required.
+- [x] An unrelated `StreamableHttpError` classifies as false.
+- [x] `AuthError::TokenRefreshFailed` and `StreamableHttpError::InsufficientScope` classify as false.
+- [x] Non-transport `ClientInitializeError` variants classify as false.
+- [x] The test requires `auth`, `client`, and `transport-streamable-http-client`, but not a concrete reqwest or Unix-socket backend.
+
+### 2. Verify the HTTP challenge source chain
+
+**Files:** `crates/rmcp/src/transport/streamable_http_client.rs`
+
+**Description:** Confirm that `AuthRequiredError` implements `std::error::Error` and that `StreamableHttpError::AuthRequired` exposes it as its source. This prerequisite is already present on the latest `origin/main`.
+
+**Acceptance criteria:**
+
+- [x] `AuthRequiredError` remains constructible through `AuthRequiredError::new`.
+- [x] `www_authenticate_header` remains available and unchanged.
+- [x] `StreamableHttpError::source()` returns the contained `AuthRequiredError`.
+- [x] Existing error display behavior remains unchanged.
+- [x] No existing enum variants or fields are removed or renamed.
+
+### 3. Add transport-independent classification
+
+**Files:** `crates/rmcp/src/transport.rs`
+
+**Description:** Add a crate-internal `DynamicTransportError::is_authorization_required()`. Walk the inner error and its sources, recognizing `AuthError::AuthorizationRequired` when `auth` is enabled and `AuthRequiredError` when the streamable HTTP client is enabled. Keep the transport-level classifier internal until another public use case requires it.
+
+**Acceptance criteria:**
+
+- [x] Client callers do not need the transport type, backend error type, or a downcast.
+- [x] Direct and multiply wrapped matching errors are recognized.
+- [x] Feature-disabled builds compile; feature-specific checks are guarded locally.
+- [x] Unknown custom transport errors return false.
+- [x] The helper name describes classification rather than an authorization action.
+
+### 4. Add the initialization-error convenience API
+
+**Files:** `crates/rmcp/src/service/client.rs`
+
+**Description:** Add `ClientInitializeError::is_authorization_required()`, delegating only when the variant is `TransportError`.
+
+**Acceptance criteria:**
+
+- [x] The issue's caller can replace its downcast helper with `error.is_authorization_required()`.
+- [x] JSON-RPC, protocol negotiation, connection-closed, and cancellation failures return false.
+- [x] The method remains available consistently across client builds.
+
+### 5. Document the recovery pattern
+
+**Files:** `docs/OAUTH_SUPPORT.md`
+
+**Description:** Extend the authorized streamable HTTP client example with a focused error-handling snippet:
+
+```rust
+match client_service.serve(transport).await {
+    Ok(client) => {
+        // use the client
+    }
+    Err(error) if error.is_authorization_required() => {
+        // return to the application's authorization flow
+    }
+    Err(error) => return Err(error.into()),
+}
+```
+
+Explain that the predicate covers both missing/expired local authorization and a server 401 challenge, while preserving the original error for logging or detailed handling.
+
+**Acceptance criteria:**
+
+- [x] The example uses only public APIs.
+- [x] The text does not suggest retrying transient failures as re-authorization.
+- [x] The text does not imply that the SDK launches a browser or authorization flow automatically.
+
+### 6. Verify compatibility and quality
+
+**Files:** All files above
+
+**Description:** Run focused tests, the relevant feature-minimal builds, and repository-wide formatting/lint checks.
+
+**Acceptance criteria:**
+
+- [x] `cargo test -p rmcp --test test_auth_error_classification --no-default-features --features "auth,client,transport-streamable-http-client"` passes.
+- [x] `cargo check -p rmcp --no-default-features --features client` passes.
+- [x] `cargo check -p rmcp --no-default-features --features "client,transport-streamable-http-client"` passes.
+- [x] `cargo test -p rmcp --all-features` passes.
+- [x] `cargo clippy -p rmcp --all-targets --all-features -- -D warnings` passes.
+- [x] `cargo fmt --all --check` passes.
+- [x] The public change is additive and does not require a SemVer exemption.
+
+## Open Questions
+
+No question blocks implementation. Before opening the PR, post the proposed additive API on #795 so the reporter and maintainers can confirm the method name. If maintainers want structured detail later, a separate API can return a reason or challenge reference without changing this predicate.