Deprecate constructing the pre-provisioned OAuth clients without an issuer

The warning becomes an MCPDeprecationWarning: omitting `issuer=` on
ClientCredentialsOAuthProvider and PrivateKeyJWTOAuthProvider keeps working
in 2.x and will be required in 3.0. The message says why (without it the MCP
server decides which authorization server receives the credentials) and what
to pass. docs/deprecated.md lists it next to the other SDK-level deprecation,
and the OAuth clients page points there.

Author: maxisbey

docs/client/oauth-clients.md

@@ -112,7 +112,7 @@ A nightly job, a CI step, another service. There is no browser and nobody to cli
 What changed:
 
 * No `OAuthClientMetadata`, no handlers. You pass `client_id` and `client_secret`; the provider builds a minimal `client_credentials` registration around them and skips dynamic registration entirely.
-* `issuer` names the authorization server that issued those credentials; use the `issuer` value its `/.well-known/oauth-authorization-server` document returns. Discovery still runs as above, but token requests are only ever built from metadata for *that* issuer; if the MCP server points anywhere else, the flow stops with an `OAuthFlowError` instead. Leave it out and the provider uses whichever authorization server discovery finds, and says so with a `UserWarning` when it is constructed.
+* `issuer` names the authorization server that issued those credentials; use the `issuer` value its `/.well-known/oauth-authorization-server` document returns. Discovery still runs as above, but token requests are only ever built from metadata for *that* issuer; if the MCP server points anywhere else, the flow stops with an `OAuthFlowError` instead. Leaving it out is deprecated and it becomes required in 3.0 (see **[Deprecated features](../deprecated.md#deprecated-sdk-helpers)**); until then the provider warns and uses whichever authorization server discovery finds.
 * `scope` is a space-separated string, the OAuth wire format.
 * Everything downstream is identical: the same `TokenStorage`, the same `httpx2.AsyncClient(auth=...)`, the same `streamable_http_client`.
 

docs/deprecated.md

@@ -1,6 +1,6 @@
 # Deprecated features
 
-The 2026-07-28 spec retires five things. The SDK still implements every one of them, and every one of them now carries a **deprecation warning**. One SDK helper is deprecated on its own account and is listed [at the end](#deprecated-sdk-helpers).
+The 2026-07-28 spec retires five things. The SDK still implements every one of them, and every one of them now carries a **deprecation warning**. Two SDK-level deprecations stand on their own account and are listed [at the end](#deprecated-sdk-helpers).
 
 The table below names each deprecated feature, why it is going away, and the replacement to build on.
 
@@ -131,11 +131,12 @@ That is the whole API. There is no per-method switch, and you don't want one: th
 
 ## Deprecated SDK helpers
 
-These are not spec changes, only SDK internals with a better replacement. They warn with the same `MCPDeprecationWarning` and will be removed in 3.0.
+These are not spec changes, only SDK usage with a better replacement. They warn with the same `MCPDeprecationWarning`, and 3.0 removes the old form.
 
 | Deprecated | What you do instead |
 |---|---|
 | `FuncMetadata.call_fn_with_arg_validation()` | `FuncMetadata.validate_arguments()` and then `FuncMetadata.call_fn()`. Only code that drives `FuncMetadata` directly (a custom `Tool` subclass, say) ever called it. |
+| `ClientCredentialsOAuthProvider(...)` or `PrivateKeyJWTOAuthProvider(...)` without `issuer=` | Pass `issuer=` naming the authorization server that issued the credentials (see **[Writing OAuth clients](client/oauth-clients.md#machine-to-machine)**). Without it the MCP server decides which authorization server receives them; 3.0 makes the keyword required. |
 
 ## Recap
 
@@ -144,7 +145,7 @@ These are not spec changes, only SDK internals with a better replacement. They w
 * Deprecated is advisory: no wire changes, everything keeps working against pre-2026 sessions, and you get a visible `MCPDeprecationWarning` (a `UserWarning`, so it is on by default).
 * Sampling and roots additionally need a back-channel that a 2026-07-28 session does not have. On a modern connection they warn and then they raise.
 * `warnings.filterwarnings("ignore", category=MCPDeprecationWarning)` silences the whole category; `"error::mcp.MCPDeprecationWarning"` in pytest turns it into a test failure.
-* One SDK helper, `FuncMetadata.call_fn_with_arg_validation()`, is deprecated separately for removal in 3.0.
+* Two SDK-level deprecations ride along: `FuncMetadata.call_fn_with_arg_validation()` is removed in 3.0, and constructing `ClientCredentialsOAuthProvider` / `PrivateKeyJWTOAuthProvider` without `issuer=` stops being allowed in 3.0.
 * New code should not be built on any of these.
 
 Every other page in these docs teaches the current API.

src/mcp/client/auth/extensions/client_credentials.py

@@ -21,13 +21,16 @@
 from mcp.client.auth.oauth2 import OAuthContext
 from mcp.client.auth.utils import issuers_match
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata
+from mcp.shared.exceptions import MCPDeprecationWarning
 
 
 def _checked_issuer(issuer: str | None) -> str | None:
     if issuer is None:
         warnings.warn(
-            "No `issuer` given: client credentials will be sent to whichever authorization server the MCP "
-            "server advertises. Pass issuer=<your authorization server's issuer URL> to send them only there.",
+            "Omitting `issuer` is deprecated and it will be required in 3.0. Without it, the MCP server "
+            "decides which authorization server receives this client's credentials; pass "
+            "issuer=<your authorization server's issuer URL> so they are only ever sent there.",
+            MCPDeprecationWarning,
             stacklevel=3,
         )
         return None
@@ -105,8 +108,9 @@ def __init__(
             issuer: The issuer identifier of the authorization server that issued
                 `client_id` and `client_secret`. When set, token requests are only built from
                 discovered authorization server metadata whose `issuer` is exactly this string;
-                otherwise the flow stops with `OAuthFlowError`. When omitted, whichever
-                authorization server discovery yields is used, and a `UserWarning` says so.
+                otherwise the flow stops with `OAuthFlowError`. Omitting it is deprecated
+                (`MCPDeprecationWarning`) and it will be required in 3.0; until then, whichever
+                authorization server discovery yields is used.
         """
         # Build minimal client_metadata for the base class
         client_metadata = OAuthClientMetadata(
@@ -335,8 +339,8 @@ def __init__(
                 registered with. When set, an assertion is only minted, and token requests
                 are only built, once authorization server metadata whose `issuer` is exactly this
                 string has been discovered; otherwise the flow stops with `OAuthFlowError`.
-                When omitted, whichever authorization server discovery yields is used, and a
-                `UserWarning` says so.
+                Omitting it is deprecated (`MCPDeprecationWarning`) and it will be required in
+                3.0; until then, whichever authorization server discovery yields is used.
         """
         # Build minimal client_metadata for the base class
         client_metadata = OAuthClientMetadata(

tests/client/auth/extensions/test_client_credentials.py

@@ -7,6 +7,7 @@
 from inline_snapshot import snapshot
 from pydantic import AnyHttpUrl
 
+from mcp import MCPDeprecationWarning
 from mcp.client.auth import OAuthClientProvider, OAuthFlowError
 from mcp.client.auth.extensions.client_credentials import (
     ClientCredentialsOAuthProvider,
@@ -446,16 +447,14 @@ async def test_provider_picks_its_configured_issuer_among_several_advertised_ser
 
 
 @pytest.mark.parametrize("kind", ["secret", "jwt"])
-def test_constructing_without_issuer_warns_where_the_credentials_will_go(
-    mock_storage: MockTokenStorage, kind: str
-) -> None:
+def test_constructing_without_issuer_is_deprecated(mock_storage: MockTokenStorage, kind: str) -> None:
     """SDK-defined: leaving `issuer` out is allowed, and the provider says at construction that
     token requests will follow whichever authorization server the MCP server advertises."""
 
     async def assertion_provider(audience: str) -> str:
         raise NotImplementedError
 
-    with pytest.warns(UserWarning) as recorded:
+    with pytest.warns(MCPDeprecationWarning) as recorded:
         if kind == "secret":
             ClientCredentialsOAuthProvider(
                 server_url=_SERVER_URL, storage=mock_storage, client_id="c", client_secret="s"
@@ -468,8 +467,9 @@ async def assertion_provider(audience: str) -> str:
     [warning] = recorded
     assert warning.filename == __file__
     assert str(warning.message) == (
-        "No `issuer` given: client credentials will be sent to whichever authorization server the MCP "
-        "server advertises. Pass issuer=<your authorization server's issuer URL> to send them only there."
+        "Omitting `issuer` is deprecated and it will be required in 3.0. Without it, the MCP server "
+        "decides which authorization server receives this client's credentials; pass "
+        "issuer=<your authorization server's issuer URL> so they are only ever sent there."
     )
 
 
@@ -484,7 +484,7 @@ async def test_without_issuer_the_exchange_follows_whichever_server_was_discover
     async def assertion_provider(audience: str) -> str:
         return "jwt"
 
-    with pytest.warns(UserWarning, match="No `issuer` given"):
+    with pytest.warns(MCPDeprecationWarning, match="Omitting `issuer` is deprecated"):
         if kind == "secret":
             provider: OAuthClientProvider = ClientCredentialsOAuthProvider(
                 server_url=_SERVER_URL, storage=mock_storage, client_id="c", client_secret="s"