feat: implement RFC9728 OAuth Protected Resource Metadata discovery

Add support for discovering OAuth authorization server metadata from
WWW-Authenticate headers per RFC9728 Section 5.1.

The MCP spec indicates that servers should return a 401 Unauthorized response
with a WWW-Authenticate header containing the resource_metadata parameter.
This parameter is used to discover the OAuth authorization server metadata.

This change adds support for this discovery, allowing clients to automatically
extract the OAuth metadata URL from the WWW-Authenticate header and use it to
discover the OAuth authorization server configuration, rather than relying
on it being on the /.well-known path of the base URL, which is not
always the case (for example,
https://mcp.linear.app/mcp/.well-known/oauth-protected-resource vs
https://mcp.honeycomb.io/.well-known/oauth-protected-resource - note the
lack of /mcp in one of these, even though both servers expect the /mcp
path in the base URL).

Changes:
- Add AuthorizationRequiredError base error type with ResourceMetadataURL field
- Add OAuthAuthorizationRequiredError that embeds AuthorizationRequiredError
- Add ProtectedResourceMetadataURL to OAuthConfig for explicit configuration
- Extract resource_metadata parameter from WWW-Authenticate headers in both
  streamable_http and sse transports
- Update getServerMetadata() to use ProtectedResourceMetadataURL when provided
- Add helper functions: IsAuthorizationRequiredError(), GetResourceMetadataURL()
- Add comprehensive tests for metadata URL extraction and usage
- Update OAuth example to demonstrate RFC9728 discovery

This allows clients to properly discover OAuth endpoints when servers return
401 responses with WWW-Authenticate headers containing resource_metadata URLs,
enabling correct OAuth flows without requiring well-known URL assumptions.

RFC9728: https://datatracker.ietf.org/doc/html/rfc9728

Author: sd2k

client/oauth.go

@@ -57,9 +57,18 @@ var GenerateCodeChallenge = transport.GenerateCodeChallenge
 // GenerateState generates a state parameter for OAuth
 var GenerateState = transport.GenerateState
 
+// AuthorizationRequiredError is returned when a 401 Unauthorized response is received
+type AuthorizationRequiredError = transport.AuthorizationRequiredError
+
 // OAuthAuthorizationRequiredError is returned when OAuth authorization is required
 type OAuthAuthorizationRequiredError = transport.OAuthAuthorizationRequiredError
 
+// IsAuthorizationRequiredError checks if an error is an AuthorizationRequiredError
+func IsAuthorizationRequiredError(err error) bool {
+	var target *AuthorizationRequiredError
+	return errors.As(err, &target)
+}
+
 // IsOAuthAuthorizationRequiredError checks if an error is an OAuthAuthorizationRequiredError
 func IsOAuthAuthorizationRequiredError(err error) bool {
 	var target *OAuthAuthorizationRequiredError
@@ -74,3 +83,23 @@ func GetOAuthHandler(err error) *transport.OAuthHandler {
 	}
 	return nil
 }
+
+// GetResourceMetadataURL extracts the protected resource metadata URL from an authorization error.
+// This URL is extracted from the WWW-Authenticate header per RFC9728 Section 5.1.
+// Works with both AuthorizationRequiredError and OAuthAuthorizationRequiredError.
+// Returns empty string if no metadata URL was discovered.
+func GetResourceMetadataURL(err error) string {
+	// Try OAuthAuthorizationRequiredError first (contains AuthorizationRequiredError)
+	var oauthErr *OAuthAuthorizationRequiredError
+	if errors.As(err, &oauthErr) {
+		return oauthErr.ResourceMetadataURL
+	}
+
+	// Try base AuthorizationRequiredError
+	var authErr *AuthorizationRequiredError
+	if errors.As(err, &authErr) {
+		return authErr.ResourceMetadataURL
+	}
+
+	return ""
+}

client/oauth_test.go

@@ -119,10 +119,93 @@ func TestIsOAuthAuthorizationRequiredError(t *testing.T) {
 	if IsOAuthAuthorizationRequiredError(err2) {
 		t.Errorf("Expected IsOAuthAuthorizationRequiredError to return false")
 	}
-
 	// Verify GetOAuthHandler returns nil
 	handler = GetOAuthHandler(err2)
 	if handler != nil {
 		t.Errorf("Expected GetOAuthHandler to return nil")
 	}
 }
+
+func TestGetResourceMetadataURL(t *testing.T) {
+	// Test with error containing metadata URL
+	metadataURL := "https://auth.example.com/.well-known/oauth-protected-resource"
+	err := &transport.OAuthAuthorizationRequiredError{
+		Handler: transport.NewOAuthHandler(transport.OAuthConfig{}),
+		AuthorizationRequiredError: transport.AuthorizationRequiredError{
+			ResourceMetadataURL: metadataURL,
+		},
+	}
+
+	// Verify GetResourceMetadataURL returns the correct URL
+	result := GetResourceMetadataURL(err)
+	if result != metadataURL {
+		t.Errorf("Expected GetResourceMetadataURL to return %q, got %q", metadataURL, result)
+	}
+
+	// Test with error containing no metadata URL
+	err2 := &transport.OAuthAuthorizationRequiredError{
+		Handler: transport.NewOAuthHandler(transport.OAuthConfig{}),
+		AuthorizationRequiredError: transport.AuthorizationRequiredError{
+			ResourceMetadataURL: "",
+		},
+	}
+
+	result2 := GetResourceMetadataURL(err2)
+	if result2 != "" {
+		t.Errorf("Expected GetResourceMetadataURL to return empty string, got %q", result2)
+	}
+
+	// Test with non-OAuth error
+	err3 := fmt.Errorf("some other error")
+
+	result3 := GetResourceMetadataURL(err3)
+	if result3 != "" {
+		t.Errorf("Expected GetResourceMetadataURL to return empty string for non-OAuth error, got %q", result3)
+	}
+}
+
+func TestIsAuthorizationRequiredError(t *testing.T) {
+	// Test with base AuthorizationRequiredError (401 without OAuth handler)
+	metadataURL := "https://auth.example.com/.well-known/oauth-protected-resource"
+	err := &transport.AuthorizationRequiredError{
+		ResourceMetadataURL: metadataURL,
+	}
+
+	// Verify IsAuthorizationRequiredError returns true
+	if !IsAuthorizationRequiredError(err) {
+		t.Errorf("Expected IsAuthorizationRequiredError to return true for AuthorizationRequiredError")
+	}
+
+	// Verify GetResourceMetadataURL returns the correct URL
+	result := GetResourceMetadataURL(err)
+	if result != metadataURL {
+		t.Errorf("Expected GetResourceMetadataURL to return %q, got %q", metadataURL, result)
+	}
+
+	// Test with OAuthAuthorizationRequiredError (different type)
+	oauthErr := &transport.OAuthAuthorizationRequiredError{
+		Handler: transport.NewOAuthHandler(transport.OAuthConfig{}),
+		AuthorizationRequiredError: transport.AuthorizationRequiredError{
+			ResourceMetadataURL: metadataURL,
+		},
+	}
+
+	// Verify IsOAuthAuthorizationRequiredError returns true
+	if !IsOAuthAuthorizationRequiredError(oauthErr) {
+		t.Errorf("Expected IsOAuthAuthorizationRequiredError to return true for OAuthAuthorizationRequiredError")
+	}
+
+	// Verify GetResourceMetadataURL works with OAuth error too
+	result2 := GetResourceMetadataURL(oauthErr)
+	if result2 != metadataURL {
+		t.Errorf("Expected GetResourceMetadataURL to return %q, got %q", metadataURL, result2)
+	}
+
+	// Test with non-authorization error
+	err3 := fmt.Errorf("some other error")
+
+	// Verify IsAuthorizationRequiredError returns false
+	if IsAuthorizationRequiredError(err3) {
+		t.Errorf("Expected IsAuthorizationRequiredError to return false for non-authorization error")
+	}
+}

client/transport/oauth.go

@@ -32,6 +32,10 @@ type OAuthConfig struct {
 	// AuthServerMetadataURL is the URL to the OAuth server metadata
 	// If empty, the client will attempt to discover it from the base URL
 	AuthServerMetadataURL string
+	// ProtectedResourceMetadataURL is the URL to the OAuth protected resource metadata
+	// per RFC9728. If set, this URL will be used to discover the authorization server.
+	// This is typically extracted from the WWW-Authenticate header's resource_metadata parameter.
+	ProtectedResourceMetadataURL string
 	// PKCEEnabled enables PKCE for the OAuth flow (recommended for public clients)
 	PKCEEnabled bool
 	// HTTPClient is an optional HTTP client to use for requests.
@@ -351,16 +355,26 @@ func (h *OAuthHandler) getServerMetadata(ctx context.Context) (*AuthServerMetada
 			return
 		}
 
-		// Try to discover the authorization server via OAuth Protected Resource
-		// as per RFC 9728 (https://datatracker.ietf.org/doc/html/rfc9728)
+		// Always extract base URL for fallback scenarios
 		baseURL, err := h.extractBaseURL()
 		if err != nil {
 			h.metadataFetchErr = fmt.Errorf("failed to extract base URL: %w", err)
 			return
 		}
 
+		// Determine the protected resource metadata URL with priority:
+		// 1. Explicit config (ProtectedResourceMetadataURL from RFC9728 WWW-Authenticate header)
+		// 2. Constructed from base URL
+		var protectedResourceURL string
+		if h.config.ProtectedResourceMetadataURL != "" {
+			// Use explicitly configured protected resource metadata URL
+			protectedResourceURL = h.config.ProtectedResourceMetadataURL
+		} else {
+			// Fall back to constructing the URL from base URL
+			protectedResourceURL = baseURL + "/.well-known/oauth-protected-resource"
+		}
+
 		// Try to fetch the OAuth Protected Resource metadata
-		protectedResourceURL := baseURL + "/.well-known/oauth-protected-resource"
 		req, err := http.NewRequestWithContext(ctx, http.MethodGet, protectedResourceURL, nil)
 		if err != nil {
 			h.metadataFetchErr = fmt.Errorf("failed to create protected resource request: %w", err)

client/transport/sse.go

@@ -148,6 +148,9 @@ func (c *SSE) Start(ctx context.Context) error {
 			if err.Error() == "no valid token available, authorization required" {
 				return &OAuthAuthorizationRequiredError{
 					Handler: c.oauthHandler,
+					AuthorizationRequiredError: AuthorizationRequiredError{
+						ResourceMetadataURL: "", // No response available in this code path
+					},
 				}
 			}
 			return fmt.Errorf("failed to get authorization header: %w", err)
@@ -162,10 +165,24 @@ func (c *SSE) Start(ctx context.Context) error {
 
 	if resp.StatusCode != http.StatusOK {
 		resp.Body.Close()
-		// Handle OAuth unauthorized error
-		if resp.StatusCode == http.StatusUnauthorized && c.oauthHandler != nil {
-			return &OAuthAuthorizationRequiredError{
-				Handler: c.oauthHandler,
+		// Handle unauthorized error
+		if resp.StatusCode == http.StatusUnauthorized {
+			// Extract discovered metadata URL per RFC9728
+			metadataURL := extractResourceMetadataURL(resp.Header.Get("WWW-Authenticate"))
+
+			// If OAuth handler exists, return OAuth-specific error
+			if c.oauthHandler != nil {
+				return &OAuthAuthorizationRequiredError{
+					Handler: c.oauthHandler,
+					AuthorizationRequiredError: AuthorizationRequiredError{
+						ResourceMetadataURL: metadataURL,
+					},
+				}
+			}
+
+			// No OAuth handler, return base authorization error
+			return &AuthorizationRequiredError{
+				ResourceMetadataURL: metadataURL,
 			}
 		}
 		return fmt.Errorf("unexpected status code: %d", resp.StatusCode)
@@ -377,6 +394,9 @@ func (c *SSE) SendRequest(
 			if err.Error() == "no valid token available, authorization required" {
 				return nil, &OAuthAuthorizationRequiredError{
 					Handler: c.oauthHandler,
+					AuthorizationRequiredError: AuthorizationRequiredError{
+						ResourceMetadataURL: "", // No response available in this code path
+					},
 				}
 			}
 			return nil, fmt.Errorf("failed to get authorization header: %w", err)
@@ -419,17 +439,29 @@ func (c *SSE) SendRequest(
 		return nil, fmt.Errorf("failed to read response body: %w", err)
 	}
 
-	// Check if we got an error response
 	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusAccepted {
-		deleteResponseChan()
+		// Handle unauthorized error
+		if resp.StatusCode == http.StatusUnauthorized {
+			// Extract discovered metadata URL per RFC9728
+			metadataURL := extractResourceMetadataURL(resp.Header.Get("WWW-Authenticate"))
+
+			// If OAuth handler exists, return OAuth-specific error
+			if c.oauthHandler != nil {
+				return nil, &OAuthAuthorizationRequiredError{
+					Handler: c.oauthHandler,
+					AuthorizationRequiredError: AuthorizationRequiredError{
+						ResourceMetadataURL: metadataURL,
+					},
+				}
+			}
 
-		// Handle OAuth unauthorized error
-		if resp.StatusCode == http.StatusUnauthorized && c.oauthHandler != nil {
-			return nil, &OAuthAuthorizationRequiredError{
-				Handler: c.oauthHandler,
+			// No OAuth handler, return base authorization error
+			return nil, &AuthorizationRequiredError{
+				ResourceMetadataURL: metadataURL,
 			}
 		}
 
+		// Read error body
 		return nil, fmt.Errorf("request failed with status %d: %s", resp.StatusCode, body)
 	}
 
@@ -521,6 +553,9 @@ func (c *SSE) SendNotification(ctx context.Context, notification mcp.JSONRPCNoti
 			if errors.Is(err, ErrOAuthAuthorizationRequired) {
 				return &OAuthAuthorizationRequiredError{
 					Handler: c.oauthHandler,
+					AuthorizationRequiredError: AuthorizationRequiredError{
+						ResourceMetadataURL: "", // No response available in this code path
+					},
 				}
 			}
 			return fmt.Errorf("failed to get authorization header: %w", err)
@@ -541,13 +576,28 @@ func (c *SSE) SendNotification(ctx context.Context, notification mcp.JSONRPCNoti
 	defer resp.Body.Close()
 
 	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusAccepted {
-		// Handle OAuth unauthorized error
-		if resp.StatusCode == http.StatusUnauthorized && c.oauthHandler != nil {
-			return &OAuthAuthorizationRequiredError{
-				Handler: c.oauthHandler,
+		// Handle unauthorized error
+		if resp.StatusCode == http.StatusUnauthorized {
+			// Extract discovered metadata URL per RFC9728
+			metadataURL := extractResourceMetadataURL(resp.Header.Get("WWW-Authenticate"))
+
+			// If OAuth handler exists, return OAuth-specific error
+			if c.oauthHandler != nil {
+				return &OAuthAuthorizationRequiredError{
+					Handler: c.oauthHandler,
+					AuthorizationRequiredError: AuthorizationRequiredError{
+						ResourceMetadataURL: metadataURL,
+					},
+				}
+			}
+
+			// No OAuth handler, return base authorization error
+			return &AuthorizationRequiredError{
+				ResourceMetadataURL: metadataURL,
 			}
 		}
 
+		// Handle other error responses
 		body, _ := io.ReadAll(resp.Body)
 		return fmt.Errorf(
 			"notification failed with status %d: %s",

client/transport/sse_oauth_test.go

@@ -239,3 +239,66 @@ func TestSSE_IsOAuthEnabled(t *testing.T) {
 		t.Errorf("Expected IsOAuthEnabled() to return true")
 	}
 }
+
+func TestSSE_OAuthMetadataDiscovery(t *testing.T) {
+	// Test that we correctly extract resource_metadata URL from WWW-Authenticate header per RFC9728
+	const expectedMetadataURL = "https://auth.example.com/.well-known/oauth-protected-resource"
+
+	// Create a test server that returns 401 with WWW-Authenticate header
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Return 401 with WWW-Authenticate header containing resource_metadata
+		w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="`+expectedMetadataURL+`"`)
+		w.WriteHeader(http.StatusUnauthorized)
+	}))
+	defer server.Close()
+
+	// Create a token store with a valid token so the request reaches the server
+	// The server will still return 401 to simulate token rejection
+	tokenStore := NewMemoryTokenStore()
+	validToken := &Token{
+		AccessToken:  "test-token",
+		TokenType:    "Bearer",
+		RefreshToken: "refresh-token",
+		ExpiresIn:    3600,
+		ExpiresAt:    time.Now().Add(1 * time.Hour), // Valid for 1 hour
+	}
+	if err := tokenStore.SaveToken(context.Background(), validToken); err != nil {
+		t.Fatalf("Failed to save token: %v", err)
+	}
+
+	// Create OAuth config
+	oauthConfig := OAuthConfig{
+		ClientID:    "test-client",
+		RedirectURI: "http://localhost:8085/callback",
+		Scopes:      []string{"mcp.read", "mcp.write"},
+		TokenStore:  tokenStore,
+		PKCEEnabled: true,
+	}
+
+	// Create SSE with OAuth
+	transport, err := NewSSE(server.URL, WithOAuth(oauthConfig))
+	if err != nil {
+		t.Fatalf("Failed to create SSE: %v", err)
+	}
+
+	// Start SSE which will trigger 401
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	err = transport.Start(ctx)
+
+	// Verify the error is an OAuthAuthorizationRequiredError
+	if err == nil {
+		t.Fatalf("Expected error, got nil")
+	}
+
+	var oauthErr *OAuthAuthorizationRequiredError
+	if !errors.As(err, &oauthErr) {
+		t.Fatalf("Expected OAuthAuthorizationRequiredError, got %T: %v", err, err)
+	}
+
+	// Verify the discovered metadata URL was extracted from WWW-Authenticate header
+	if oauthErr.ResourceMetadataURL != expectedMetadataURL {
+		t.Errorf("Expected ResourceMetadataURL to be %q, got %q",
+			expectedMetadataURL, oauthErr.ResourceMetadataURL)
+	}
+}