Align OAuth client with spec on PKCE verification and scope selection

Two changes to how the OAuth client uses discovered authorization-server
metadata, both required by the MCP authorization specification.

Verify PKCE support before the authorization-code grant. The spec's
Authorization Code Protection section requires clients to verify PKCE
support from the authorization server's metadata and to refuse to
proceed when code_challenge_methods_supported is absent. The new
validate_pkce_support() also refuses a method list that omits S256,
since that is the only method this client sends. The check sits at the
top of _perform_authorization_code_grant, so it covers both the initial
401 flow and the 403 insufficient_scope step-up, while grants that never
issue an authorization code (client credentials, private key JWT) are
unaffected. When no metadata document was discovered at all the flow
proceeds as before: absence of a document is not evidence of
non-support.

Stop reading scopes_supported from authorization-server metadata when
selecting a scope. The spec's scope-selection chain is the
WWW-Authenticate scope parameter, then the protected-resource metadata's
scopes_supported, otherwise omit the scope parameter. The SDK inserted
an extra fallback to the authorization server's scopes_supported, which
over-requests (an authorization server may serve many resource servers,
so its list is a superset of any one resource's) and causes
access_denied failures against servers that reject unknown scopes. With
the fallback removed, clients that relied on it should pass an explicit
scope on their OAuthClientMetadata.

Closes #1307

Author: maxisbey

docs/advanced/oauth-clients.md

@@ -78,7 +78,7 @@ The first time `Client` sends a request, the server answers `401`. The provider
 
 1. **Discovery.** It reads the `WWW-Authenticate` header, fetches the server's Protected Resource Metadata from `/.well-known/oauth-protected-resource`, learns which authorization server protects this resource, and fetches *that* server's metadata.
 2. **Registration.** Nothing in storage? It registers you dynamically with your `OAuthClientMetadata` and stores the result.
-3. **Authorization.** It generates the PKCE pair and a `state`, builds the authorization URL, awaits your `redirect_handler`, then awaits your `callback_handler` for the code.
+3. **Authorization.** It checks that the discovered authorization-server metadata advertises `S256` PKCE support (and stops with `OAuthFlowError` if it does not), generates the PKCE pair and a `state`, builds the authorization URL, awaits your `redirect_handler`, then awaits your `callback_handler` for the code.
 4. **Exchange.** It trades the code for an `OAuthToken`, stores it, and replays your original request with `Authorization: Bearer ...`.
 
 After that it is quiet. Tokens come out of storage, an expired access token is refreshed with the refresh token, and only when none of that works does it run the flow again.

docs/migration.md

@@ -121,6 +121,18 @@ async def callback_handler() -> AuthorizationCodeResult:
 
 Forward the `iss` query parameter from the redirect so the validation can run: omitting it makes the flow fail with `OAuthFlowError` against servers that advertise `authorization_response_iss_parameter_supported`, and silently skips the check for servers that send `iss` without advertising it.
 
+### OAuth client refuses to authorize when AS metadata does not advertise S256 PKCE
+
+The OAuth client now verifies PKCE support before starting the authorization-code grant, as the MCP authorization specification's Authorization Code Protection section requires. When an authorization-server metadata document was discovered and its `code_challenge_methods_supported` is absent (which the spec defines as "the authorization server does not support PKCE") or does not list `S256` (the only method the SDK sends), the flow raises `OAuthFlowError` instead of redirecting to the authorization endpoint. The symptom is `OAuthFlowError: Authorization server metadata does not include code_challenge_methods_supported; PKCE support cannot be verified`. Previously the SDK never inspected the field and proceeded with an S256 challenge regardless.
+
+When no authorization-server metadata document could be discovered at all, the flow proceeds as before — absence of a document is not evidence of non-support. Grants that never issue an authorization code (`ClientCredentialsOAuthProvider`, `PrivateKeyJWTOAuthProvider`) are unaffected. There is no SDK-side opt-out: an authorization server that supports S256 but omits the field from its published metadata needs that metadata fixed (RFC 8414 §2 defines `code_challenge_methods_supported`).
+
+### OAuth client no longer reads `scopes_supported` from AS metadata to choose a scope
+
+The specification's scope-selection chain is two steps: the `scope` parameter from the `WWW-Authenticate` challenge, then `scopes_supported` from the Protected Resource Metadata document, *otherwise the `scope` parameter is omitted*. The SDK inserted an extra fallback between those two steps — the **authorization-server** metadata's `scopes_supported` — which over-requests (an authorization server may serve many resource servers, so its list is a superset of any one resource's) and caused real `access_denied` failures ([#1307](https://github.com/modelcontextprotocol/python-sdk/issues/1307)). That fallback is removed: when neither the challenge nor the PRM names scopes, the client now omits the `scope` parameter and lets the authorization server apply its defaults.
+
+This also affects the SEP-2207 `offline_access` augmentation, which only fires once a base scope was selected: if the authorization server's `scopes_supported` was your only scope source, the client now sends no `scope` at all (not even `offline_access`) and the authorization server's defaults decide whether a refresh token is issued. In either case, if you relied on the removed fallback, pass an explicit `scope` on the `OAuthClientMetadata` you give to `OAuthClientProvider`.
+
 ### `get_session_id` callback removed from `streamable_http_client`
 
 The `get_session_id` callback (third element of the returned tuple) has been removed from `streamable_http_client`. The function now returns a 2-tuple `(read_stream, write_stream)` instead of a 3-tuple.

src/mcp/client/auth/oauth2.py

@@ -21,6 +21,7 @@
 
 from mcp.client.auth.exceptions import OAuthFlowError, OAuthTokenError
 from mcp.client.auth.utils import (
+    CODE_CHALLENGE_METHOD,
     build_oauth_authorization_server_metadata_discovery_urls,
     build_protected_resource_metadata_discovery_urls,
     create_client_info_from_metadata_url,
@@ -40,6 +41,7 @@
     union_scopes,
     validate_authorization_response_iss,
     validate_metadata_issuer,
+    validate_pkce_support,
 )
 from mcp.shared.auth import (
     AuthorizationCodeResult,
@@ -323,6 +325,12 @@ async def _perform_authorization_code_grant(self) -> tuple[str, str]:
         if not self.context.callback_handler:
             raise OAuthFlowError("No callback handler provided for authorization code grant")  # pragma: no cover
 
+        # Authorization Code Protection: a discovered metadata document that does not advertise
+        # S256 PKCE support must stop the flow before any authorize redirect is built. When no
+        # document was discovered at all there is nothing to verify against, so the flow proceeds.
+        if self.context.oauth_metadata is not None:
+            validate_pkce_support(self.context.oauth_metadata)
+
         if self.context.oauth_metadata and self.context.oauth_metadata.authorization_endpoint:
             auth_endpoint = str(self.context.oauth_metadata.authorization_endpoint)
         else:
@@ -342,7 +350,7 @@ async def _perform_authorization_code_grant(self) -> tuple[str, str]:
             "redirect_uri": str(self.context.client_metadata.redirect_uris[0]),
             "state": state,
             "code_challenge": pkce_params.code_challenge,
-            "code_challenge_method": "S256",
+            "code_challenge_method": CODE_CHALLENGE_METHOD,
         }
 
         # Only include resource param if conditions are met

src/mcp/client/auth/utils.py

@@ -1,4 +1,5 @@
 import re
+from typing import Final
 from urllib.parse import urljoin, urlparse
 
 from httpx import Request, Response
@@ -15,6 +16,10 @@
 )
 from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
 
+# The only PKCE code challenge method this client sends (OAuth 2.1 section 4.1.1 mandates S256).
+# `validate_pkce_support` checks the authorization server's metadata against the same name.
+CODE_CHALLENGE_METHOD: Final = "S256"
+
 
 def extract_field_from_www_auth(response: Response, field_name: str) -> str | None:
     """Extract field from WWW-Authenticate header.
@@ -107,14 +112,11 @@ def get_client_metadata_scopes(
     # MCP spec scope selection priority:
     #   1. WWW-Authenticate header scope
     #   2. PRM scopes_supported
-    #   3. AS scopes_supported (SDK fallback)
-    #   4. Omit scope parameter
+    #   3. Omit scope parameter
     if www_authenticate_scope is not None:
         selected_scope = www_authenticate_scope
     elif protected_resource_metadata is not None and protected_resource_metadata.scopes_supported is not None:
         selected_scope = " ".join(protected_resource_metadata.scopes_supported)
-    elif authorization_server_metadata is not None and authorization_server_metadata.scopes_supported is not None:
-        selected_scope = " ".join(authorization_server_metadata.scopes_supported)
 
     # SEP-2207: append offline_access when the AS supports it and the client can use refresh tokens
     if (
@@ -272,6 +274,30 @@ def validate_metadata_issuer(oauth_metadata: OAuthMetadata, expected_issuer: str
         )
 
 
+def validate_pkce_support(oauth_metadata: OAuthMetadata) -> None:
+    """Verify that authorization-server metadata advertises support for S256 PKCE.
+
+    Per the MCP authorization specification's Authorization Code Protection requirements, a
+    client must verify PKCE support from the authorization server's metadata before proceeding
+    with authorization: an absent `code_challenge_methods_supported` means the server does not
+    support PKCE. The SDK only ever sends the mandatory `S256` method, so a method list that
+    omits `S256` is equally unusable.
+
+    Raises:
+        OAuthFlowError: If `code_challenge_methods_supported` is absent or does not list `S256`.
+    """
+    methods = oauth_metadata.code_challenge_methods_supported
+    if methods is None:
+        raise OAuthFlowError(
+            "Authorization server metadata does not include code_challenge_methods_supported; "
+            "PKCE support cannot be verified"
+        )
+    if CODE_CHALLENGE_METHOD not in methods:
+        raise OAuthFlowError(
+            f"Authorization server does not support the {CODE_CHALLENGE_METHOD} PKCE code challenge method: {methods}"
+        )
+
+
 def create_oauth_metadata_request(url: str) -> Request:
     return Request("GET", url, headers={MCP_PROTOCOL_VERSION_HEADER: LATEST_PROTOCOL_VERSION})
 

tests/client/test_auth.py

@@ -30,6 +30,7 @@
     union_scopes,
     validate_authorization_response_iss,
     validate_metadata_issuer,
+    validate_pkce_support,
 )
 from mcp.server.auth.routes import build_metadata
 from mcp.server.auth.settings import ClientRegistrationOptions, RevocationOptions
@@ -2447,7 +2448,11 @@ def test_offline_access_not_duplicated_when_already_present(self):
         assert scopes == "read offline_access write"
 
     def test_offline_access_not_added_when_no_scopes_selected(self):
-        """offline_access is not added when no base scopes are available (None)."""
+        """offline_access is not appended when the challenge and PRM yield no base scope.
+
+        The AS metadata advertising offline_access is not a scope source, so there is no
+        selected scope to augment and the result stays None.
+        """
         asm = self._make_as_metadata(scopes_supported=["offline_access"])
 
         scopes = get_client_metadata_scopes(
@@ -2456,9 +2461,7 @@ def test_offline_access_not_added_when_no_scopes_selected(self):
             authorization_server_metadata=asm,
             client_grant_types=["authorization_code", "refresh_token"],
         )
-        # When AS scopes are the only source and include offline_access,
-        # the base scope is "offline_access" and no duplication happens
-        assert scopes == "offline_access"
+        assert scopes is None
 
     def test_offline_access_not_added_when_as_scopes_supported_is_none(self):
         """offline_access is not added when AS scopes_supported is None."""
@@ -2571,6 +2574,7 @@ async def callback_handler() -> AuthorizationCodeResult:
                 b'{"issuer": "https://auth.example.com",'
                 b' "authorization_endpoint": "https://auth.example.com/authorize",'
                 b' "token_endpoint": "https://auth.example.com/token",'
+                b' "code_challenge_methods_supported": ["S256"],'
                 b' "scopes_supported": ["read", "write", "offline_access"]}'
             ),
             request=oauth_request,
@@ -2679,6 +2683,7 @@ async def callback_handler() -> AuthorizationCodeResult:
                 b'{"issuer": "https://auth.example.com",'
                 b' "authorization_endpoint": "https://auth.example.com/authorize",'
                 b' "token_endpoint": "https://auth.example.com/token",'
+                b' "code_challenge_methods_supported": ["S256"],'
                 b' "scopes_supported": ["read", "write"]}'
             ),
             request=oauth_request,
@@ -2780,6 +2785,48 @@ def test_validate_metadata_issuer_rejects_mismatch():
         validate_metadata_issuer(_issuer_metadata(issuer="https://attacker.example.com"), _ISSUER)
 
 
+def test_as_metadata_scopes_supported_is_never_used_as_a_scope_source():
+    """When neither the challenge nor the PRM names scopes, scope is omitted even though the AS advertises some.
+
+    The spec's scope-selection chain is WWW-Authenticate scope, then PRM scopes_supported, then
+    omit; authorization-server metadata is not a step in it.
+    """
+    asm = OAuthMetadata(
+        issuer=AnyHttpUrl("https://auth.example.com"),
+        authorization_endpoint=AnyHttpUrl("https://auth.example.com/authorize"),
+        token_endpoint=AnyHttpUrl("https://auth.example.com/token"),
+        scopes_supported=["as-only:read", "as-only:write"],
+    )
+    assert get_client_metadata_scopes(None, None, asm) is None
+
+
+def test_pkce_validation_passes_when_as_metadata_lists_s256():
+    """Metadata whose code_challenge_methods_supported includes S256 is accepted, whatever else it lists."""
+    validate_pkce_support(_issuer_metadata().model_copy(update={"code_challenge_methods_supported": ["plain", "S256"]}))
+
+
+def test_pkce_validation_refuses_when_code_challenge_methods_supported_is_absent():
+    """An AS metadata document without code_challenge_methods_supported is refused: PKCE support is unverified."""
+    metadata = _issuer_metadata()
+    assert metadata.code_challenge_methods_supported is None
+    with pytest.raises(OAuthFlowError) as exc_info:
+        validate_pkce_support(metadata)
+    assert str(exc_info.value) == snapshot(
+        "Authorization server metadata does not include code_challenge_methods_supported; "
+        "PKCE support cannot be verified"
+    )
+
+
+def test_pkce_validation_refuses_when_s256_is_not_among_the_advertised_methods():
+    """A code_challenge_methods_supported list without S256 is refused: the SDK only sends S256."""
+    metadata = _issuer_metadata().model_copy(update={"code_challenge_methods_supported": ["plain"]})
+    with pytest.raises(OAuthFlowError) as exc_info:
+        validate_pkce_support(metadata)
+    assert str(exc_info.value) == snapshot(
+        "Authorization server does not support the S256 PKCE code challenge method: ['plain']"
+    )
+
+
 @pytest.mark.parametrize(
     ("previous", "new", "expected"),
     [
@@ -2980,7 +3027,8 @@ async def test_issuer_binding_re_evaluated_after_asm_when_prm_discovery_failed(
                     content=(
                         b'{"issuer": "https://new-as.example.com", '
                         b'"authorization_endpoint": "https://new-as.example.com/authorize", '
-                        b'"token_endpoint": "https://new-as.example.com/token"}'
+                        b'"token_endpoint": "https://new-as.example.com/token", '
+                        b'"code_challenge_methods_supported": ["S256"]}'
                     ),
                 )
             ],
@@ -3127,7 +3175,8 @@ async def echo_callback() -> AuthorizationCodeResult:
         content=(
             b'{"issuer": "https://api.example.com", '
             b'"authorization_endpoint": "https://api.example.com/authorize", '
-            b'"token_endpoint": "https://api.example.com/token"}'
+            b'"token_endpoint": "https://api.example.com/token", '
+            b'"code_challenge_methods_supported": ["S256"]}'
         ),
         request=asm_req,
     )
@@ -3158,3 +3207,79 @@ async def echo_callback() -> AuthorizationCodeResult:
         await auth_flow.asend(httpx.Response(200, request=final_req))
     except StopAsyncIteration:
         pass
+
+
+@pytest.mark.anyio
+async def test_pkce_is_still_sent_when_no_authorization_server_metadata_document_is_discovered(
+    oauth_provider: OAuthClientProvider,
+):
+    """With no discoverable AS metadata, the client still proceeds and sends an S256 PKCE challenge.
+
+    The refuse-if-unsupported gate is conditioned on a discovered authorization-server metadata
+    *document*: failing to obtain one is not evidence of non-support, and the SDK deliberately
+    keeps a legacy no-metadata fallback path (the `client-auth:prm-discovery:no-prm-fallback`
+    requirement), so the flow falls back to the resource origin's `/authorize` with PKCE intact.
+    This has to drive the httpx `async_auth_flow` generator directly: the in-process interaction
+    harness cannot express a server with no metadata endpoint, because its real authorize route
+    always returns an RFC 9207 `iss` that the client rejects when it has no metadata issuer to
+    compare against.
+
+    Steps:
+      1. 401 with no challenge -> path-based then root PRM discovery, both 404.
+      2. One root AS-metadata probe (the only URL built when no AS is known), 404 ->
+         `oauth_metadata` stays None.
+      3. DCR against the resource origin's `/register` fallback.
+      4. The authorize redirect is built and carries `code_challenge_method=S256`.
+    """
+    oauth_provider.context.current_tokens = None
+    oauth_provider.context.token_expiry_time = None
+    oauth_provider._initialized = True
+
+    captured_url: str | None = None
+
+    async def capture_redirect(url: str) -> None:
+        nonlocal captured_url
+        captured_url = url
+
+    async def echo_callback() -> AuthorizationCodeResult:
+        assert captured_url is not None
+        params = parse_qs(urlparse(captured_url).query)
+        return AuthorizationCodeResult(code="auth_code", state=params["state"][0])
+
+    oauth_provider.context.redirect_handler = capture_redirect
+    oauth_provider.context.callback_handler = echo_callback
+
+    auth_flow = oauth_provider.async_auth_flow(httpx.Request("GET", "https://api.example.com/v1/mcp"))
+    request = await auth_flow.__anext__()
+
+    prm_req = await auth_flow.asend(httpx.Response(401, request=request))
+    assert str(prm_req.url) == "https://api.example.com/.well-known/oauth-protected-resource/v1/mcp"
+    prm_req = await auth_flow.asend(httpx.Response(404, request=prm_req))
+    assert str(prm_req.url) == "https://api.example.com/.well-known/oauth-protected-resource"
+
+    asm_req = await auth_flow.asend(httpx.Response(404, request=prm_req))
+    assert str(asm_req.url) == "https://api.example.com/.well-known/oauth-authorization-server"
+    dcr_req = await auth_flow.asend(httpx.Response(404, request=asm_req))
+    assert oauth_provider.context.oauth_metadata is None
+    assert str(dcr_req.url) == "https://api.example.com/register"
+
+    token_req = await auth_flow.asend(
+        httpx.Response(
+            201,
+            json={"client_id": "registered", "redirect_uris": ["http://localhost:3030/callback"]},
+            request=dcr_req,
+        )
+    )
+
+    assert captured_url is not None
+    params = parse_qs(urlparse(captured_url).query)
+    assert params["code_challenge_method"] == ["S256"]
+    assert params["code_challenge"] != [""]
+
+    final_req = await auth_flow.asend(
+        httpx.Response(200, json={"access_token": "t", "token_type": "Bearer", "expires_in": 3600}, request=token_req)
+    )
+    try:
+        await auth_flow.asend(httpx.Response(200, request=final_req))
+    except StopAsyncIteration:
+        pass