feat: expose oauth discovery metadata source

[DaleSeo]

Closes#1037

Motivation and Context

The previous AuthorizationManager::discover_metadata() method fell back to the legacy default endpoints, /authorize, /token, and /register, based on the base URL when discovery returned nothing. This fallback is required for the auth/2025-03-26-oauth-endpoint-fallback conformance scenario. However, it made a successful fallback look the same as metadata that the server actually published. As a result, callers could not tell whether OAuth metadata was discovered or synthesized for compatibility. That behavior was originally introduced in #507 and changed by #960.

This replaces that method with AuthorizationManager::resolve_metadata(), which returns AuthorizationMetadataResolution containing both the AuthorizationMetadata and its AuthorizationMetadataSource. “Resolve” reflects that the method may either discover server-published metadata or synthesize legacy endpoints. The source distinguishes protected resource metadata, authorization server metadata, and the legacy endpoint fallback; is_discovered() reports whether the server published metadata.

Because v3 is still in beta, this makes provenance part of the primary metadata-resolution contract now instead of adding a parallel method that would need to be retained long-term. Internal SDK and conformance call sites explicitly extract .metadata; the discovery order, legacy endpoint synthesis, and conformance behavior remain unchanged.

How Has This Been Tested?

Unit tests cover all three sources

Breaking Changes

AuthorizationManager::discover_metadata() has been renamed to resolve_metadata() and now returns Result<AuthorizationMetadataResolution, AuthError> instead of Result<AuthorizationMetadata, AuthError>.

Callers must use the new method and extract the metadata field when they need AuthorizationMetadata directly:

// Beforelet metadata = manager.discover_metadata().await?;
manager.set_metadata(metadata);// Afterlet resolution = manager.resolve_metadata().await?;
manager.set_metadata(resolution.metadata);

Callers can inspect resolution.source or call resolution.source.is_discovered() before consuming the metadata.

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

[alexhancock]

I would include something here if we're going to have a descriptive comment that metadata discovery is now mandatory in newer versions of the spec, and there is no endpoint-synthesis fallback any more.

https://modelcontextprotocol.io/specification/draft/basic/authorization/authorization-server-discovery#protected-resource-metadata-discovery-requirements

[DaleSeo]

Closes#1037

Motivation and Context

The previous AuthorizationManager::discover_metadata() method fell back to the legacy default endpoints, /authorize, /token, and /register, based on the base URL when discovery returned nothing. This fallback is required for the auth/2025-03-26-oauth-endpoint-fallback conformance scenario. However, it made a successful fallback look the same as metadata that the server actually published. As a result, callers could not tell whether OAuth metadata was discovered or synthesized for compatibility. That behavior was originally introduced in #507 and changed by #960.

This replaces that method with AuthorizationManager::resolve_metadata(), which returns AuthorizationMetadataResolution containing both the AuthorizationMetadata and its AuthorizationMetadataSource. “Resolve” reflects that the method may either discover server-published metadata or synthesize legacy endpoints. The source distinguishes protected resource metadata, authorization server metadata, and the legacy endpoint fallback; is_discovered() reports whether the server published metadata.

Because v3 is still in beta, this makes provenance part of the primary metadata-resolution contract now instead of adding a parallel method that would need to be retained long-term. Internal SDK and conformance call sites explicitly extract .metadata; the discovery order, legacy endpoint synthesis, and conformance behavior remain unchanged.

How Has This Been Tested?

Unit tests cover all three sources

Breaking Changes

AuthorizationManager::discover_metadata() has been renamed to resolve_metadata() and now returns Result<AuthorizationMetadataResolution, AuthError> instead of Result<AuthorizationMetadata, AuthError>.

Callers must use the new method and extract the metadata field when they need AuthorizationMetadata directly:

// Beforelet metadata = manager.discover_metadata().await?;
manager.set_metadata(metadata);// Afterlet resolution = manager.resolve_metadata().await?;
manager.set_metadata(resolution.metadata);

Callers can inspect resolution.source or call resolution.source.is_discovered() before consuming the metadata.

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

[alexhancock]

I would include something here if we're going to have a descriptive comment that metadata discovery is now mandatory in newer versions of the spec, and there is no endpoint-synthesis fallback any more.

https://modelcontextprotocol.io/specification/draft/basic/authorization/authorization-server-discovery#protected-resource-metadata-discovery-requirements

[DaleSeo]

Closes#1037

Motivation and Context

The previous AuthorizationManager::discover_metadata() method fell back to the legacy default endpoints, /authorize, /token, and /register, based on the base URL when discovery returned nothing. This fallback is required for the auth/2025-03-26-oauth-endpoint-fallback conformance scenario. However, it made a successful fallback look the same as metadata that the server actually published. As a result, callers could not tell whether OAuth metadata was discovered or synthesized for compatibility. That behavior was originally introduced in #507 and changed by #960.

This replaces that method with AuthorizationManager::resolve_metadata(), which returns AuthorizationMetadataResolution containing both the AuthorizationMetadata and its AuthorizationMetadataSource. “Resolve” reflects that the method may either discover server-published metadata or synthesize legacy endpoints. The source distinguishes protected resource metadata, authorization server metadata, and the legacy endpoint fallback; is_discovered() reports whether the server published metadata.

Because v3 is still in beta, this makes provenance part of the primary metadata-resolution contract now instead of adding a parallel method that would need to be retained long-term. Internal SDK and conformance call sites explicitly extract .metadata; the discovery order, legacy endpoint synthesis, and conformance behavior remain unchanged.

How Has This Been Tested?

Unit tests cover all three sources

Breaking Changes

AuthorizationManager::discover_metadata() has been renamed to resolve_metadata() and now returns Result<AuthorizationMetadataResolution, AuthError> instead of Result<AuthorizationMetadata, AuthError>.

Callers must use the new method and extract the metadata field when they need AuthorizationMetadata directly:

// Beforelet metadata = manager.discover_metadata().await?;
manager.set_metadata(metadata);// Afterlet resolution = manager.resolve_metadata().await?;
manager.set_metadata(resolution.metadata);

Callers can inspect resolution.source or call resolution.source.is_discovered() before consuming the metadata.

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

[alexhancock]

I would include something here if we're going to have a descriptive comment that metadata discovery is now mandatory in newer versions of the spec, and there is no endpoint-synthesis fallback any more.

https://modelcontextprotocol.io/specification/draft/basic/authorization/authorization-server-discovery#protected-resource-metadata-discovery-requirements

[DaleSeo]

Closes#1037

Motivation and Context

The previous AuthorizationManager::discover_metadata() method fell back to the legacy default endpoints, /authorize, /token, and /register, based on the base URL when discovery returned nothing. This fallback is required for the auth/2025-03-26-oauth-endpoint-fallback conformance scenario. However, it made a successful fallback look the same as metadata that the server actually published. As a result, callers could not tell whether OAuth metadata was discovered or synthesized for compatibility. That behavior was originally introduced in #507 and changed by #960.

This replaces that method with AuthorizationManager::resolve_metadata(), which returns AuthorizationMetadataResolution containing both the AuthorizationMetadata and its AuthorizationMetadataSource. “Resolve” reflects that the method may either discover server-published metadata or synthesize legacy endpoints. The source distinguishes protected resource metadata, authorization server metadata, and the legacy endpoint fallback; is_discovered() reports whether the server published metadata.

Because v3 is still in beta, this makes provenance part of the primary metadata-resolution contract now instead of adding a parallel method that would need to be retained long-term. Internal SDK and conformance call sites explicitly extract .metadata; the discovery order, legacy endpoint synthesis, and conformance behavior remain unchanged.

How Has This Been Tested?

Unit tests cover all three sources

Breaking Changes

AuthorizationManager::discover_metadata() has been renamed to resolve_metadata() and now returns Result<AuthorizationMetadataResolution, AuthError> instead of Result<AuthorizationMetadata, AuthError>.

Callers must use the new method and extract the metadata field when they need AuthorizationMetadata directly:

// Beforelet metadata = manager.discover_metadata().await?;
manager.set_metadata(metadata);// Afterlet resolution = manager.resolve_metadata().await?;
manager.set_metadata(resolution.metadata);

Callers can inspect resolution.source or call resolution.source.is_discovered() before consuming the metadata.

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

[alexhancock]

I would include something here if we're going to have a descriptive comment that metadata discovery is now mandatory in newer versions of the spec, and there is no endpoint-synthesis fallback any more.

https://modelcontextprotocol.io/specification/draft/basic/authorization/authorization-server-discovery#protected-resource-metadata-discovery-requirements

[DaleSeo]

Closes#1037

Motivation and Context

The previous AuthorizationManager::discover_metadata() method fell back to the legacy default endpoints, /authorize, /token, and /register, based on the base URL when discovery returned nothing. This fallback is required for the auth/2025-03-26-oauth-endpoint-fallback conformance scenario. However, it made a successful fallback look the same as metadata that the server actually published. As a result, callers could not tell whether OAuth metadata was discovered or synthesized for compatibility. That behavior was originally introduced in #507 and changed by #960.

This replaces that method with AuthorizationManager::resolve_metadata(), which returns AuthorizationMetadataResolution containing both the AuthorizationMetadata and its AuthorizationMetadataSource. “Resolve” reflects that the method may either discover server-published metadata or synthesize legacy endpoints. The source distinguishes protected resource metadata, authorization server metadata, and the legacy endpoint fallback; is_discovered() reports whether the server published metadata.

Because v3 is still in beta, this makes provenance part of the primary metadata-resolution contract now instead of adding a parallel method that would need to be retained long-term. Internal SDK and conformance call sites explicitly extract .metadata; the discovery order, legacy endpoint synthesis, and conformance behavior remain unchanged.

How Has This Been Tested?

Unit tests cover all three sources

Breaking Changes

AuthorizationManager::discover_metadata() has been renamed to resolve_metadata() and now returns Result<AuthorizationMetadataResolution, AuthError> instead of Result<AuthorizationMetadata, AuthError>.

Callers must use the new method and extract the metadata field when they need AuthorizationMetadata directly:

// Beforelet metadata = manager.discover_metadata().await?;
manager.set_metadata(metadata);// Afterlet resolution = manager.resolve_metadata().await?;
manager.set_metadata(resolution.metadata);

Callers can inspect resolution.source or call resolution.source.is_discovered() before consuming the metadata.

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

[alexhancock]

I would include something here if we're going to have a descriptive comment that metadata discovery is now mandatory in newer versions of the spec, and there is no endpoint-synthesis fallback any more.

https://modelcontextprotocol.io/specification/draft/basic/authorization/authorization-server-discovery#protected-resource-metadata-discovery-requirements

[DaleSeo]

Closes#1037

Motivation and Context

The previous AuthorizationManager::discover_metadata() method fell back to the legacy default endpoints, /authorize, /token, and /register, based on the base URL when discovery returned nothing. This fallback is required for the auth/2025-03-26-oauth-endpoint-fallback conformance scenario. However, it made a successful fallback look the same as metadata that the server actually published. As a result, callers could not tell whether OAuth metadata was discovered or synthesized for compatibility. That behavior was originally introduced in #507 and changed by #960.

This replaces that method with AuthorizationManager::resolve_metadata(), which returns AuthorizationMetadataResolution containing both the AuthorizationMetadata and its AuthorizationMetadataSource. “Resolve” reflects that the method may either discover server-published metadata or synthesize legacy endpoints. The source distinguishes protected resource metadata, authorization server metadata, and the legacy endpoint fallback; is_discovered() reports whether the server published metadata.

Because v3 is still in beta, this makes provenance part of the primary metadata-resolution contract now instead of adding a parallel method that would need to be retained long-term. Internal SDK and conformance call sites explicitly extract .metadata; the discovery order, legacy endpoint synthesis, and conformance behavior remain unchanged.

How Has This Been Tested?

Unit tests cover all three sources

Breaking Changes

AuthorizationManager::discover_metadata() has been renamed to resolve_metadata() and now returns Result<AuthorizationMetadataResolution, AuthError> instead of Result<AuthorizationMetadata, AuthError>.

Callers must use the new method and extract the metadata field when they need AuthorizationMetadata directly:

// Beforelet metadata = manager.discover_metadata().await?;
manager.set_metadata(metadata);// Afterlet resolution = manager.resolve_metadata().await?;
manager.set_metadata(resolution.metadata);

Callers can inspect resolution.source or call resolution.source.is_discovered() before consuming the metadata.

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

[alexhancock]

I would include something here if we're going to have a descriptive comment that metadata discovery is now mandatory in newer versions of the spec, and there is no endpoint-synthesis fallback any more.

https://modelcontextprotocol.io/specification/draft/basic/authorization/authorization-server-discovery#protected-resource-metadata-discovery-requirements

[DaleSeo]

Closes#1037

Motivation and Context

The previous AuthorizationManager::discover_metadata() method fell back to the legacy default endpoints, /authorize, /token, and /register, based on the base URL when discovery returned nothing. This fallback is required for the auth/2025-03-26-oauth-endpoint-fallback conformance scenario. However, it made a successful fallback look the same as metadata that the server actually published. As a result, callers could not tell whether OAuth metadata was discovered or synthesized for compatibility. That behavior was originally introduced in #507 and changed by #960.

This replaces that method with AuthorizationManager::resolve_metadata(), which returns AuthorizationMetadataResolution containing both the AuthorizationMetadata and its AuthorizationMetadataSource. “Resolve” reflects that the method may either discover server-published metadata or synthesize legacy endpoints. The source distinguishes protected resource metadata, authorization server metadata, and the legacy endpoint fallback; is_discovered() reports whether the server published metadata.

Because v3 is still in beta, this makes provenance part of the primary metadata-resolution contract now instead of adding a parallel method that would need to be retained long-term. Internal SDK and conformance call sites explicitly extract .metadata; the discovery order, legacy endpoint synthesis, and conformance behavior remain unchanged.

How Has This Been Tested?

Unit tests cover all three sources

Breaking Changes

AuthorizationManager::discover_metadata() has been renamed to resolve_metadata() and now returns Result<AuthorizationMetadataResolution, AuthError> instead of Result<AuthorizationMetadata, AuthError>.

Callers must use the new method and extract the metadata field when they need AuthorizationMetadata directly:

// Beforelet metadata = manager.discover_metadata().await?;
manager.set_metadata(metadata);// Afterlet resolution = manager.resolve_metadata().await?;
manager.set_metadata(resolution.metadata);

Callers can inspect resolution.source or call resolution.source.is_discovered() before consuming the metadata.

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

[alexhancock]

I would include something here if we're going to have a descriptive comment that metadata discovery is now mandatory in newer versions of the spec, and there is no endpoint-synthesis fallback any more.

https://modelcontextprotocol.io/specification/draft/basic/authorization/authorization-server-discovery#protected-resource-metadata-discovery-requirements

[DaleSeo]

Closes#1037

Motivation and Context

The previous AuthorizationManager::discover_metadata() method fell back to the legacy default endpoints, /authorize, /token, and /register, based on the base URL when discovery returned nothing. This fallback is required for the auth/2025-03-26-oauth-endpoint-fallback conformance scenario. However, it made a successful fallback look the same as metadata that the server actually published. As a result, callers could not tell whether OAuth metadata was discovered or synthesized for compatibility. That behavior was originally introduced in #507 and changed by #960.

This replaces that method with AuthorizationManager::resolve_metadata(), which returns AuthorizationMetadataResolution containing both the AuthorizationMetadata and its AuthorizationMetadataSource. “Resolve” reflects that the method may either discover server-published metadata or synthesize legacy endpoints. The source distinguishes protected resource metadata, authorization server metadata, and the legacy endpoint fallback; is_discovered() reports whether the server published metadata.

Because v3 is still in beta, this makes provenance part of the primary metadata-resolution contract now instead of adding a parallel method that would need to be retained long-term. Internal SDK and conformance call sites explicitly extract .metadata; the discovery order, legacy endpoint synthesis, and conformance behavior remain unchanged.

How Has This Been Tested?

Unit tests cover all three sources

Breaking Changes

AuthorizationManager::discover_metadata() has been renamed to resolve_metadata() and now returns Result<AuthorizationMetadataResolution, AuthError> instead of Result<AuthorizationMetadata, AuthError>.

Callers must use the new method and extract the metadata field when they need AuthorizationMetadata directly:

// Beforelet metadata = manager.discover_metadata().await?;
manager.set_metadata(metadata);// Afterlet resolution = manager.resolve_metadata().await?;
manager.set_metadata(resolution.metadata);

Callers can inspect resolution.source or call resolution.source.is_discovered() before consuming the metadata.

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

[alexhancock]

I would include something here if we're going to have a descriptive comment that metadata discovery is now mandatory in newer versions of the spec, and there is no endpoint-synthesis fallback any more.

https://modelcontextprotocol.io/specification/draft/basic/authorization/authorization-server-discovery#protected-resource-metadata-discovery-requirements