Fix: Relax resource URI validation to accept base URL

[JBallan]

Fix #1119

Summary

Per MCP specification, OAuth authorization operates at the base URL level (path discarded). The SDK now accepts OAuth metadata when the resource field contains either:

• The full MCP endpoint URI (e.g., https://server.example.com/mcp/tools)
• The base URL only (e.g., https://server.example.com)

This aligns with RFC 9728 § 3.1 which states that protected resource metadata can be scoped at the authority level.

Motivation and Context

The SDK's OAuth client was throwing a validation error when the resource field in OAuth protected resource metadata returned the base URL instead of the full MCP endpoint path. This prevented legitimate OAuth flows where servers declare protected resources at the authority level, which is:

• ✅ Spec-compliant per MCP OAuth specification
• ✅ Valid per RFC 9728 § 3.1 (authorization server metadata)
• ✅ Common practice for multi-endpoint OAuth servers

Example scenario that now works:

• Resource metadata: https://server.example.com MCP
• Endpoint: https://server.example.com/mcp/tools

↑ Now validates successfully

Implementation Details

Updated OAuthClientHandler.TryGetResourceMetadataAsync:

• Compares base URLs (scheme + authority) when resource URI has no path
• Falls back to full URI comparison for backward compatibility
• Maintains security by rejecting mismatched authorities

How Has This Been Tested?

Test Changes

Renamed test:

• CannotAuthenticate_WhenWwwAuthenticateResourceMetadataIsRootPath → CanAuthenticate_WhenWwwAuthenticateResourceMetadataIsRootPath
  • Purpose: Verifies OAuth succeeds when resource metadata URI is root-level while MCP endpoint has a subpath
  • Validates: Flexible URI matching behavior

New test:

• CannotAuthenticate_WhenResourceMetadataUriDoesNotMatch
  • Purpose: Ensures authentication fails when resource URI points to a completely different server
  • Validates: Security - prevents cross-server token misuse

Breaking Changes

No breaking changes. This is a behavioral enhancement that makes OAuth resource URI validation more flexible while maintaining backward compatibility.

Behavior Change Details

Previous behavior:

• OAuth resource URI validation required strict matching between the protected resource metadata URI and the MCP endpoint URI.

New behavior:

• OAuth resource URI validation now follows a more flexible matching strategy that aligns with the MCP specification:
• A resource URI without a path (e.g., https://server.example.com) will successfully match endpoints with paths (e.g., https://server.example.com/mcp/tools)
• This allows servers to declare protected resources at a broader scope while still protecting specific endpoints

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 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

[JBallan]

Hi! The workflows are currently awaiting approval, so CodeQL checks can't run yet and the PR is blocked. Could a maintainer approve the workflows and review the PR when possible? Thanks!

[JBallan]

Could a maintainer review the PR when possible? Thanks!

[matt-gribben]

Hope somebody reviews this soon... the current strict evaluation of URI's breaks the SDK Client for a lot of popular MCP services (Linear for example)

[scrodde]

This is a real issue could a reviewer have a look? @tarekgh @halter73 @mikekistler @jeffhandley

[tarekgh]

I'll take a look today.

[tarekgh]

I suggest if we can edit the section https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#canonical-server-uri (in another PR) relaxing the statement aligns with the resource parameter in RFC 9728 to something like effectively extending the RFC 9728's resource parameter validation model

[tarekgh]

nit (minor): The comment at ClientOAuthProvider.cs line 926 (in the PR branch) at the VerifyResourceMatch call site still says:

// Per RFC: The resource value must be identical to the URL that the client used to make the request to the resource server

Since VerifyResourceMatch now also accepts authority-level matches, this comment could be misleading to a future reader. Consider softening it to reflect the relaxed matching, e.g.:

// Per RFC 9728, validate that the resource URI in metadata corresponds to the server we're connecting to.
// VerifyResourceMatch accepts both exact URI match and authority-level (base URL) match per MCP spec.

[tarekgh]

Added minor comment, LGTM otherwise.