ClientOAuthProvider.Scopes have priority again (#1236)

[halllo]

I adjusted the priority of scope determination. Scopes specified via ClientOAuthOptions.Scopes have priority over scopes from PRM.

Motivation and Context

When the client specifies Scopes via the ClientOAuthOptions, these scopes are used before the scopes of the PRM, just as the xml comment states

"When specified, these scopes will be used instead of the scopes advertised by the protected resource.".

For example this is needed if a client only supports a subset of PRM scopes or wants to add the offline_access scope.

How Has This Been Tested?

I added test method.

Breaking Changes

No. Unless they unexpectedly rely on ClientOAuthOptions.Scopes not having an effect in the presence of PRM scopes.

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

This addresses #1236

[halter73]

I think we should update the doc comments to indicate that ClientOAuthOptions.Scopes is only a fallback. Or maybe we need to split between ScopesFallback and ScopesOverride.

The November version of the MCP spec added a "Scope Selection Strategy" we now implement.

Scope Selection Strategy

When implementing authorization flows, MCP clients SHOULD follow the principle of least privilege by requesting
only the scopes necessary for their intended operations. During the initial authorization handshake, MCP clients
SHOULD follow this priority order for scope selection:

1. Use scope parameter from the initial WWW-Authenticate header in the 401 response, if provided
2. If scope is not available, use all scopes defined in scopes_supported from the Protected Resource Metadata document, omitting the scope parameter if scopes_supported is undefined.

This approach accommodates the general-purpose nature of MCP clients, which typically lack domain-specific knowledge to make informed decisions about individual scope selection. Requesting all available scopes allows the authorization server and end-user to determine appropriate permissions during the consent process.

This approach minimizes user friction while following the principle of least privilege.
The scopes_supported field is intended to represent the minimal set of scopes necessary
for basic functionality (see Scope Minimization),
with additional scopes requested incrementally through the step-up authorization flow steps
described in the Scope Challenge Handling section.

https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#scope-selection-strategy

Do we know what the other SDK's do here?

[halter73]

I asked Copilot what the TS and Python SDK do, and it appears the client-developer-provided scopes are only used as a fallback.

TypeScript SDK (modelcontextprotocol/typescript-sdk): scope selection precedence is explicit and matches the spec (+ uses client scope as last fallback)

In the TypeScript client OAuth implementation, the scope passed into the authorization-start call is selected with this precedence chain:

1. explicit scope argument (this comes from WWW-Authenticate: ... scope="..." when a 401 happens, via middleware), else
2. scopes_supported from Protected Resource Metadata (PRM), else
3. provider.clientMetadata.scope (client-configured scope)

// Start new authorization flow
const { authorizationUrl, codeVerifier } = await startAuthorization(authorizationServerUrl, {
    metadata,
    clientInformation,
    state,
    redirectUrl: provider.redirectUrl,
    scope: scope || resourceMetadata?.scopes_supported?.join(' ') || provider.clientMetadata.scope,
    resource
});

The TypeScript SDK also explicitly parses scope out of the WWW-Authenticate header:

export function extractWWWAuthenticateParams(res: Response): { resourceMetadataUrl?: URL; scope?: string; error?: string } {
    const authenticateHeader = res.headers.get('WWW-Authenticate');
    if (!authenticateHeader) {
        return {};
    }

    const [type, scheme] = authenticateHeader.split(' ');
    if (type?.toLowerCase() !== 'bearer' || !scheme) {
        return {};
    }

    // ...
    const scope = extractFieldFromWwwAuth(res, 'scope') || undefined;
    const error = extractFieldFromWwwAuth(res, 'error') || undefined;

    return {
        resourceMetadataUrl,
        scope,
        error
    };
}

And their tests assert the key spec behaviors:

• if scope is not provided, use PRM scopes_supported
• explicit scope beats PRM

// Call auth without scope parameter
const result = await auth(mockProvider, {
    serverUrl: 'https://api.example.com/'
});

// Verify the authorization URL includes the scopes from PRM
const redirectCall = (mockProvider.redirectToAuthorization as Mock).mock.calls[0]!;
const authUrl: URL = redirectCall[0];
expect(authUrl?.searchParams.get('scope')).toBe('mcp:read mcp:write mcp:admin');

(There is also a test named prefers explicit scope parameter over scopes_supported from PRM immediately after this snippet in the same file.)

So: TypeScript treats client-provided clientMetadata.scope as a last-resort fallback, not as an override that always wins.

Note: my lexical search output warns it’s limited to 10 results; if you want to browse more occurrences in GitHub UI, here’s the search:
https://github.com/modelcontextprotocol/typescript-sdk/search?q=repo%3Amodelcontextprotocol%2Ftypescript-sdk+path%3Apackages%2Fclient%2Fsrc%2Fclient%2Fauth.ts+%28scopes_supported+OR+WWW-Authenticate+OR+extractWWWAuthenticateParams%29&type=code

---

Python SDK (modelcontextprotocol/python-sdk): implements the MCP “Scope Selection Strategy” directly; client-configured scope gets overwritten

The Python SDK has a dedicated helper with an explicit docstring and comments stating the strategy and priority:

1. WWW-Authenticate scope
2. PRM scopes_supported
3. (extra fallback) Authorization Server Metadata scopes_supported (RFC 8414)
4. omit scope parameter

def get_client_metadata_scopes(
    www_authenticate_scope: str | None,
    protected_resource_metadata: ProtectedResourceMetadata | None,
    authorization_server_metadata: OAuthMetadata | None = None,
) -> str | None:
    """Select scopes as outlined in the 'Scope Selection Strategy' in the MCP spec."""
    # Per MCP spec, scope selection priority order:
    # 1. Use scope from WWW-Authenticate header (if provided)
    # 2. Use all scopes from PRM scopes_supported (if available)
    # 3. Omit scope parameter if neither is available

    if www_authenticate_scope is not None:
        # Priority 1: WWW-Authenticate header scope
        return www_authenticate_scope
    elif protected_resource_metadata is not None and protected_resource_metadata.scopes_supported is not None:
        # Priority 2: PRM scopes_supported
        return " ".join(protected_resource_metadata.scopes_supported)
    elif authorization_server_metadata is not None and authorization_server_metadata.scopes_supported is not None:
        return " ".join(authorization_server_metadata.scopes_supported)  # pragma: no cover
    else:
        # Priority 3: Omit scope parameter
        return None

Crucially: during auth flow, Python sets self.context.client_metadata.scope based on that selection strategy—meaning any user-provided client_metadata.scope becomes effectively a fallback that can be overwritten:

# Step 3: Apply scope selection strategy
self.context.client_metadata.scope = get_client_metadata_scopes(
    extract_scope_from_www_auth(response),
    self.context.protected_resource_metadata,
    self.context.oauth_metadata,
)

And on “step-up” (insufficient_scope) it again updates scope from the 401:

if error == "insufficient_scope":  # pragma: no branch
    # Step 2a: Update the required scopes
    self.context.client_metadata.scope = get_client_metadata_scopes(
        extract_scope_from_www_auth(response), self.context.protected_resource_metadata
    )

And when building the authorize URL, it includes scope only if client_metadata.scope is set:

if self.context.client_metadata.scope:  # pragma: no branch
    auth_params["scope"] = self.context.client_metadata.scope

So: Python is very clearly “spec-first”: WWW-Authenticate wins, else PRM scopes_supported; client-provided scopes are not an override. It even adds an extra fallback to authorization-server metadata scopes_supported.

---

Comparison / implication for C# docs

Both SDKs treat a client-configured scope as fallback, not “highest priority override”:

• TypeScript: WWW-Authenticate scope / explicit scope param > PRM scopes_supported > client metadata scope
• Python: WWW-Authenticate scope > PRM scopes_supported > (AS metadata scopes_supported) > omit; and it overwrites client_metadata.scope based on this.

@halllo Can you explain the scenario where you need to override the scopes explicitly requested by the MCP server? Is this a scenario that works with any clients that do not use the MCP C# SDK?

[halllo]

That is very interesting, because I find it counter-intuitive that the values I explicitly provide are not used.
My main scenario is the addition of the offline_access scope to get the refresh token. The offline_access scope is not a scope that’s in PRM, because it is not part of the resource. However it is needed to get refresh tokens for long running sessions.
Another scenario is that my client supports only a subset of the scopes of PRM (and therefore only a subset of tools), so when it tries to use the scopes from PRM, token acquisition fails because of unsupported scopes.

Alternatively additional integration points (e.g. custom scope selection) would also help me to have more control over what scopes are actually used.

[halllo]

What do you think about this?

await using var transport = new HttpClientTransport(new()
{
    ...
    OAuth = new()
    {
        ...
        CustomScopeSelector = scopes => $"{scopes} offline_access".Trim(),
    },
});

private string? GetScopeParameter(ProtectedResourceMetadata protectedResourceMetadata)
{
    var scopeParameter = default(string?);
    if (!string.IsNullOrEmpty(protectedResourceMetadata.WwwAuthenticateScope))
    {
        scopeParameter = protectedResourceMetadata.WwwAuthenticateScope;
    }
    else if (protectedResourceMetadata.ScopesSupported.Count > 0)
    {
        scopeParameter = string.Join(" ", protectedResourceMetadata.ScopesSupported);
    }
    else
    {
        scopeParameter = _configuredScopes;
    }

    if (_customScopeSelector is not null)
    {
        scopeParameter = _customScopeSelector.Invoke(scopeParameter);
    }

    return scopeParameter;
}

Then ClientOAuthOptions.Scopes would be just a fallback.

[halllo]

As a workaround I manipulate the scope query parameter of the authorization URL before I redirect the user.

var httpClientTransport = new HttpClientTransport(new()
{
	...
	OAuth = new()
	{
		...
		AuthorizationRedirectDelegate = HandleAuthorizationUrlAsync,
	},
}, http);

static async Task<string?> HandleAuthorizationUrlAsync(Uri authUrl, Uri redirectUri, CancellationToken cancellationToken)
{
	static Uri changeScopes(Uri url, Func<string[], string[]> adjustScopes)
	{
		return new Uri(Regex.Replace(url.ToString(), @"(?<=&scope=)(?<scopes>[^&]+)", m =>
		{
			var scopes = m.Groups["scopes"].Value;
			return string.Join('+', adjustScopes(scopes.Split('+', StringSplitOptions.RemoveEmptyEntries)));
		}));
	}

	var newAuthUrl = changeScopes(authUrl, scopes => [.. scopes, "offline_access"]);
	Console.WriteLine($"Starting OAuth authorization flow at {newAuthUrl}");
	...
}

This works as long as the library does not use pushed authorization requests.

[halter73]

I just merged #1479, which implements SEP-2207's offline_access augmentation. The SDK now automatically appends offline_access to the authorization request whenever the Authorization Server advertises it in scopes_supported with no client configuration needed. I think that covers your primary scenario.

That leaves the "my client only supports a subset of PRM scopes" case. I don't think a priority inversion is the right fix for it:

The MCP Scope Selection Strategy says priority is WWW-Authenticate → PRM scopes_supported → omit. The TS and Python SDKs both treat client-configured scopes as fallback only. Having C# silently disagree would be a real interop hazard.

A general-purpose MCP client usually shouldn't be narrowing PRM-advertised scopes — the spec's guidance is that requesting all advertised scopes lets the AS and end user decide via consent.

If a specific client genuinely needs to filter scopes, your AuthorizationRedirectDelegate workaround already covers that (and a future ScopeSelector hook could make it first-class without changing default behavior).

My preference is to:

1. Close this PR.

2. Update the XML doc on ClientOAuthOptions.Scopes to make clear it's a fallback used only when the AS challenge and PRM don't supply scopes.

3. If the subset-filtering scenario is something you still need, open a separate issue proposing a ScopeSelector hook — that's a cleaner extension point than a priority swap.

Does that work for you? I'd be happy to take a small doc-only PR from you but definitely don't feel obligated. I can do that myself too.

[halllo]

I think always automatically adding the offline_access scope when AS supports it, can be problematic. If the client configuration did not explicitly enable offline access for that client and the client requests it, the authorization would fail with "unsupported/invalid scope".

I agree with the interoperability argument.

My workaround with AuthorizationRedirectDelegate only works as long as it is not using RFC 9126 PAR. The better solution would be a ScopeSelector. I am going to start a dedicated PR for that and also update the docs.

[halter73]

Thanks! I see #1596 is already up — appreciate you getting on it quickly.

On the offline_access concern: I agree it's a real failure mode in principle, but I'd lean toward keeping the auto-append as the default. Both the TS SDK (typescript-sdk#1523) and the Python SDK (python-sdk#2039) ship the same SEP-2207 behavior, so changing the default in C# would diverge from the other reference implementations. Happy to revisit if you start seeing this fail in practice.