Authorization Server & Protected Resource Metadata inspection

Start with ClientOAuthOptions and the MCP client path that fetches authorization server and protected resource metadata. Review the existing AuthorizationRedirectDelegate and related authentication code, then compare the proposed delegate and ClientOAuthEvents designs, including the caching question. Done means the chosen public API exposes the requested metadata access consistently and has coverage for the selected callbacks.

Sometimes we need access to the AS metadata & PRM. For example, if we want to implement logout we need access to the logout endpoint which resides on the AS metadata, and this AS metadata is already fetched by the MCP client. Another use case is to conditionally inspect the claims in the access token based on the AS that was used for the authentication (e.g getting the user name & display name claims etc.)

a.

One design might be to add a few more delegates to ClientOAuthOptions:

namespace ModelContextProtocol.Authentication;

public sealed class ClientOAuthOptions
{
    ...

    /// <summary>
    /// Gets or sets the delegate called when authorization server metadata is retrieved.
    /// </summary>
    public Action<AuthorizationServerMetadata> OnAuthorizationServerMetadataRetrieved { get; set; }

    /// <summary>
    /// Gets or sets the delegate called when protected resource metadata is retrieved.
    /// </summary>
    public Action<ProtectedResourceMetadata> OnProtectedResourceMetadataRetrieved { get; set; }

    ...
}

Having them as delegates/events avoids having to manage and expose state on the McpClient instance.

b.

Another design might be to use something similar to the pattern in used by ASP.NET Core auth.

namespace ModelContextProtocol.Authentication;

public sealed class RetrievingAuthorizationServerMetadataContext ...;
public sealed class RetrievedAuthorizationServerMetadataContext ...;

public sealed class RetrievingProtectedResourceMetadataContext ...;
public sealed class RetrievedProtectedResourceMetadataContext ...;

public sealed class ClientOAuthEvents
{
    /// <summary>
    /// Gets or sets the delegate called before authorization server metadata is retrieved.
    /// </summary>
    public Func<RetrievingAuthorizationServerMetadataContext, Task> OnRetrievingAuthorizationServerMetadata { get; set; } = ...;

    /// <summary>
    /// Gets or sets the delegate called after authorization server metadata is retrieved.
    /// </summary>
    public Func<RetrievedAuthorizationServerMetadataContext, Task> OnRetrievedAuthorizationServerMetadata { get; set; } = ...;

    /// <summary>
    /// Gets or sets the delegate called before protected resource metadata is retrieved.
    /// </summary>
    public Func<RetrievingProtectedResourceMetadataContext, Task> OnRetrievingProtectedResourceMetadata { get; set; } = ...;

    /// <summary>
    /// Gets or sets the delegate called after protected resource metadata is retrieved.
    /// </summary>
    public Func<RetrievedProtectedResourceMetadataContext, Task> OnRetrievedProtectedResourceMetadata { get; set; } = ...;
}

public sealed class ClientOAuthOptions
{
    ...

    /// <summary>
    /// Gets or sets the <see cref="ClientOAuthEvents" />.
    /// </summary>
    public ClientOAuthEvents Events { get; set; } = new();

    ...
}

The idea behind the "Retrieving" variants is that it allows the user to implement metadata caching, although it also expands the ability for the user to shoot themselves in the foot. I suppose it depends on if caching is a user level concern or a library level concern.

The AuthorizationRedirectDelegate on ClientOAuthOptions can also be moved into the ClientOAuthEvents class to make the surface more uniform.

The overall surface may be reduced if we combine them into a single OnRetrievedMetadata and OnRetrievingMetadata, but trickiness in the contexts I suppose.