Append offline_access to authorization scope when AS advertises it (SEP-2207)

[Copilot]

SEP-2207 specifies that MCP clients MAY add offline_access to the authorization request scope when the Authorization Server's scopes_supported metadata includes it, signaling to OIDC-flavored servers that a refresh token is desired. The SDK was not doing this.

Changes

• ClientOAuthProvider: Added AugmentScopeWithOfflineAccess helper called from BuildAuthorizationUrl after GetScopeParameter. Appends offline_access only when the AS advertises it in scopes_supported and it isn't already present in the scope string.

• TestOAuthServer: Added IncludeOfflineAccessInMetadata property (default false) to opt the test AS into advertising offline_access in scopes_supported.

• AuthTests: Three new integration tests covering: augmentation when AS advertises offline_access, no augmentation when it doesn't, and no duplication when it's already in the scope.

// AS metadata: scopes_supported = ["openid", "mcp:tools", "offline_access"]
// PRM scope: "mcp:tools"
// → authorization request scope: "mcp:tools offline_access"

// AS metadata: scopes_supported = ["openid", "mcp:tools"]  (no offline_access)
// PRM scope: "mcp:tools"
// → authorization request scope: "mcp:tools"  (unchanged)

Original prompt

Context

SEP-2207 (now merged) provides OIDC-flavored refresh token guidance for MCP OAuth clients. The C# SDK already satisfies all MUST/SHOULD requirements, but there is one MAY-level enhancement that the spec explicitly calls for reference implementations in official SDKs to adopt.

Problem

The SEP states that MCP Clients MAY add offline_access to the scope parameter in the authorization request when the Authorization Server metadata (scopes_supported) contains "offline_access". This signals to OIDC-flavored authorization servers that the client desires a refresh token.

Currently, ClientOAuthProvider.BuildAuthorizationUrl() and related methods pass through scopes from the protected resource metadata or configured scopes, but never augment them with offline_access by checking AuthorizationServerMetadata.ScopesSupported.

Desired Change

In ClientOAuthProvider, after determining the scope string to use (via GetScopeParameter), check if authServerMetadata.ScopesSupported contains "offline_access". If it does, and offline_access is not already present in the scope string, append it before sending the authorization request.

Key locations to change:

1. ClientOAuthProvider.cs — Modify scope construction in BuildAuthorizationUrl (and optionally ExchangeCodeForTokenAsync) to augment the scope with offline_access when:

   • authServerMetadata.ScopesSupported contains "offline_access"
   • The current scope string does not already include offline_access

2. Tests — Add test coverage verifying that:

   • offline_access is appended to the authorization URL scope when the AS metadata advertises it in scopes_supported
   • offline_access is NOT added when the AS metadata does not include it
   • offline_access is NOT duplicated if it's already present in the configured scopes

Important notes:

• The AuthorizationServerMetadata class already has ScopesSupported (scopes_supported) deserialized, so no model changes are needed.
• The BuildAuthorizationUrl method already receives authServerMetadata as a parameter, so it has access to the needed information.
• This is a client-side only change; no server-side changes are needed.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Is there any work needed in the C# SDK to adapt to this PR?

Assistant:

Let me examine the referenced PR and the current state of the C# SDK to understand what changes might be needed.

Assistant: Now let me look at the C# SDK's OAuth/authorization client code to see how it currently handles scopes, grant types, and refresh tokens:

Assistant: Now let me look at the key areas more closely — the GetScopeParameter method and BuildAuthorizationUrl to understand how scopes are currently assembled for the authorization request, and the AuthorizationServerMetadata to check for scopes_supported:

Assistant: Based on my thorough analysis of the PR and the C# SDK codebase, here's my assessment:

SEP-2207 Impact on the C# SDK

The C# SDK already partially complies with the SEP-2207 guidance, but there is one concrete client-side improvement that could be made as a reference implementation, and everything else is already in good shape.

✅ What's already correct

1. Dynamic Client Registration already includes refresh_token in grant_types — In ClientOAuthProvider.cs line 651, the DCR request already sends GrantTypes = ["authorization_code", "refresh_token"], which satisfies the SHOULD requirement that clients include refresh_token in their grant_types client metadata.

2. Refresh token handling is already implemented — The SDK already stores, retrieves, and uses refresh tokens via RefreshTokensAsync(), GetAccessTokenSilentAsync(), and the token cache infrastructure.

3. No server-side offline_access violation — The SDK's server-side code does not include offline_access in WWW-Authenticate scope or Protected Resource Metadata scopes_supported, which aligns with the SHOULD NOT guidance.

🔧 What could be added (optional, MAY-level)

The SEP says MCP Clients MAY add offline_access to the scope parameter when the Authorization Server metadata contains it in scopes_supported. The C# SDK currently does not do this — the BuildAuthorizationUrl and [GetScopeParameter](https://github.com/modelcontextprotocol/csharp-sdk/blob/7662ce6b7092c1b026f7613ed3e79a658192fa83/src/ModelContextProtocol.Core/Authentication/ClientOAuthProvider.cs...

This pull request was created from Copilot chat.