GeezerVison

v1.x backport of #3398 and #3435.

The OAuth client on 1.x now decides which issuer it expects before it fetches any authorization server metadata and checks what follows against that one value: the metadata's issuer (RFC 8414 section 3.3), which 1.x did not check on any path; the binding of stored client credentials to the authorization server they were registered with, which 1.x did not have; and a 403 scope step-up that goes through the same discovery when no metadata is held. The two machine-to-machine providers gain the optional issuer= keyword.

Motivation and Context

Same as #3398. On 1.x the client accepted authorization server metadata without comparing its issuer to the URL the well-known was built from, and stored client_id/client_secret carried no record of which server issued them, so they were presented to whichever authorization server the resource advertised next (or, on the 2025-03-26 fallback, to the resource server's own origin). This brings the 1.x client to the behaviour main has: the expected issuer is the PRM-advertised server, or on the no-PRM path the resource server's origin; metadata that names anything else is refused (a root issuer with and without its trailing slash is the same server); a registration bound to a different issuer is dropped, together with its tokens, before any metadata is fetched, and the client re-registers; newly registered clients are bound to the expected issuer; a 403 insufficient_scope with no metadata held discovers first; a 5xx/429 on the resource metadata request with no location answering stops the flow; and ClientCredentialsOAuthProvider / PrivateKeyJWTOAuthProvider accept issuer= so pre-provisioned credentials only go to that server.

Because 1.x had no credential binding, this also carries the parts of #2921, #2933, #2936, #2946 and #3181 that the change relies on: OAuthClientInformationFull.issuer (recorded by the SDK, never read from a registration response), validate_metadata_issuer, credentials_match_issuer and issuers_match in mcp.client.auth.utils, and the registration step recording the issuer.

Differences from #3398:

• RFC 9207 iss validation is not included; the callback contract on 1.x stays tuple[str, str | None].
• 1.x has no SEP-2350 scope union, so a step-up asks for the challenged scope as before.
• Every parsed issuer renders with a trailing slash on 1.x, so the root-slash allowance lives in validate_metadata_issuer itself (new here) rather than only on the legacy path, and recorded issuers carry the slash.
• The issuer= keyword follows scopes (the 1.x name); there is no docs page for these providers on 1.x, so the docstrings carry the description.
• Deprecate constructing the pre-provisioned OAuth clients without an issuer #3435's deprecation of constructing the two providers without issuer= is included as a third commit; 1.x has no MCPDeprecationWarning, so it warns with DeprecationWarning like the other deprecations on this branch, and the note lives in the docstrings (1.x has no deprecations docs page).
• The conformance harness pinned on 1.x (0.1.13) serves, in auth/metadata-var2 and auth/metadata-var3, authorization server metadata whose issuer omits the tenant path its resource metadata advertises, so a client that checks RFC 8414 section 3.3 refuses it. Those two scenarios are listed in expected-failures.yml with that note; the mock includes the path from conformance 0.1.15 (fix: include tenant path in auth server issuer claim conformance#152), so the entries go when the pin moves past it. (Bumping the pin here instead would trade them for two unrelated baseline entries, so that is left for its own change.)

How Has This Been Tested?

New tests in tests/client/test_auth.py and tests/client/auth/extensions/test_client_credentials.py, ported from #3398 and from main's credential-binding suite: issuer check on the PRM and legacy paths, root-slash tolerance and its limits, binding kept/discarded/stamped/not-stamped cases, registration responses cannot seed the binding, legacy path with no metadata (from a 401 and from a 403), step-up with and without metadata held, non-challenge 403, PRM 5xx/429, issuer= on both providers. The flow tests were checked to fail against v1.x's oauth2.py with the new helpers in place (they import functions 1.x did not have, so the plain "restore src/" recipe cannot collect them). I also drove the 1.x provider through httpx.AsyncClient(auth=...) and streamablehttp_client against local test servers for the PRM and legacy paths, 401-first and 403-first, and client-credentials with and without issuer=. Full suite, coverage, pyright and ruff pass locally.

Breaking Changes

No API removals or signature changes; additions are the optional issuer= keyword, the optional OAuthClientInformationFull.issuer field (round-trips through the unchanged TokenStorage methods; the server side does not emit it), and three functions in mcp.client.auth.utils. Observable differences:

• Authorization server metadata whose issuer is not the advertised server (or, without protected resource metadata, the resource server's origin) now gets OAuthFlowError: Authorization server metadata issuer mismatch. No client-side override, as on main.
• Stored credentials the SDK registers from now on carry an issuer; when the resource later names a different authorization server they are discarded and the client re-registers (one extra POST /register). Records stored by earlier 1.x releases carry no issuer and are left as they are.
• A scope step-up performs discovery first when no metadata is held; a 403 without insufficient_scope is no longer retried.
• When no protected resource metadata location answers and one returned a 5xx or 429, the flow raises instead of taking the legacy path.
• An issuer member in a dynamic client registration response is ignored.

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 am assigned to the linked issue (or it is labeled help wanted, or I'm a maintainer)
• I have disclosed any AI assistance and can explain the change in my own words
• 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

Three commits: the discovery change (with the binding layer it needs on 1.x), the issuer= keyword, then its deprecation-when-omitted from #3435. The discovery block in async_auth_flow is re-indented under one new condition; the whitespace-insensitive view is the easier read.

_{AI Disclaimer}