SEP-2207: Refresh token guidance

[wdawson]

Implement OIDC-flavored refresh token guidance (SEP-2207) in the Python SDK client.

Motivation and Context

MCP clients interacting with OIDC-flavored Authorization Servers often don't receive refresh tokens because they aren't requesting offline_access. This leads to poor UX (frequent re-authentication). SEP-2207 provides guidance for how MCP clients should handle this.

The Python SDK's default OAuthClientMetadata already includes refresh_token in grant_types, but the client was not augmenting authorization request scopes with offline_access when the Authorization Server advertises support for it. This change brings the Python SDK in line with the TypeScript SDK's implementation.

How Has This Been Tested?

• 10 unit tests covering all edge cases for offline_access scope augmentation in get_client_metadata_scopes
• 2 end-to-end auth flow tests verifying the authorization request includes (or excludes) offline_access and prompt=consent based on AS metadata

Breaking Changes

None. This is additive behavior. Clients that previously did not request offline_access will now request it automatically when the AS advertises it in scopes_supported and the client supports the refresh_token grant. Authorization Servers that don't recognize offline_access will simply ignore it per OAuth 2.1.

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

Additional context

• get_client_metadata_scopes() now accepts client_grant_types and appends offline_access to the selected scopes when the AS metadata advertises it in scopes_supported and the client includes refresh_token in its grant_types.
• The authorization request includes prompt=consent when offline_access is in the scope, per the OIDC Core spec. This matches the TypeScript SDK's behavior.
• The 403 insufficient_scope handler now also passes AS metadata and client grant types to get_client_metadata_scopes, fixing a pre-existing omission.