feat: classify authorization-required client errors

Let clients detect re-authorization requirements without depending on a
specific HTTP backend error type or discarding the original challenge details.

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,32 @@ impl DynamicTransportError {
         }
     }
 
+    /// Returns whether this transport error means the client must authorize again.
+    ///
+    /// This recognizes both an exhausted local OAuth authorization and an HTTP
+    /// authorization challenge without requiring the caller to know or downcast
+    /// the concrete transport error type.
+    pub 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,97 @@
+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 dynamic(error: impl Error + Send + Sync + 'static) -> DynamicTransportError {
+    DynamicTransportError::from_parts("test transport", TypeId::of::<()>(), Box::new(error))
+}
+
+fn initialization_error(error: TestHttpError) -> ClientInitializeError {
+    ClientInitializeError::TransportError {
+        error: dynamic(error),
+        context: "initialize".into(),
+    }
+}
+
+#[test]
+fn classifies_local_authorization_required() {
+    let error = TestHttpError::Auth(AuthError::AuthorizationRequired);
+
+    assert!(dynamic(error).is_authorization_required());
+}
+
+#[test]
+fn classifies_http_authorization_challenge() {
+    let error =
+        TestHttpError::AuthRequired(AuthRequiredError::new("Bearer realm=\"mcp\"".to_owned()));
+
+    assert!(dynamic(error).is_authorization_required());
+}
+
+#[test]
+fn classifies_authorization_required_through_multiple_sources() {
+    let error = OuterError(TestHttpError::Auth(AuthError::AuthorizationRequired));
+
+    assert!(dynamic(error).is_authorization_required());
+}
+
+#[test]
+fn client_initialization_error_delegates_to_transport_classification() {
+    let local = initialization_error(TestHttpError::Auth(AuthError::AuthorizationRequired));
+    let challenge = initialization_error(TestHttpError::AuthRequired(AuthRequiredError::new(
+        "Bearer realm=\"mcp\"".to_owned(),
+    )));
+
+    assert!(local.is_authorization_required());
+    assert!(challenge.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!(!dynamic(closed).is_authorization_required());
+    assert!(!dynamic(refresh).is_authorization_required());
+    assert!(!dynamic(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\"");
+    assert_eq!(source.to_string(), "authorization required");
+}