Warn when AuthSettings.validate_token_resource is left unset

validate_token_resource becomes bool | None (default None). With a
resource_server_url configured and no explicit choice, AuthSettings emits an
MCPDeprecationWarning and behaves as False, so existing deployments keep
working but are asked to decide; 3.0 makes True the default. An explicit
False (the verifier checks the audience itself) is silent.

The docs tutorials, the bearer_auth and oauth_client_credentials stories,
and the oauth_server snippet now set it to True and issue tokens bound to
their resource URL; docs/deprecated.md lists the new warning.

Author: maxisbey

docs/deprecated.md

@@ -136,6 +136,7 @@ These are not spec changes, only SDK usage with a better replacement. They warn
 | 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. |
+| `AuthSettings(resource_server_url=...)` without `validate_token_resource=` | Set it: `True` has the server refuse bearer tokens your verifier does not report as issued for `resource_server_url`, `False` says your verifier checks the token's audience itself (see **[Authorization](run/authorization.md#a-token-verifier)**). Unset behaves as `False`; 3.0 makes `True` the default. |
 | `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

docs/run/authorization.md

@@ -18,20 +18,20 @@ That's the whole triangle. Everything on this page is the middle bullet.
 
 The SDK has no opinion about what a valid token looks like. You tell it, by implementing **`TokenVerifier`**:
 
-```python title="server.py" hl_lines="12-14 19-24"
+```python title="server.py" hl_lines="14-16 21-27"
 --8<-- "docs_src/authorization/tutorial001.py"
 ```
 
 * `TokenVerifier` is a protocol with one async method. `verify_token` gets the raw token from the `Authorization` header and returns an **`AccessToken`** if it's valid, `None` if it isn't. There is nothing else to implement.
-* This one looks the token up in a table. A real one verifies a JWT signature or calls the authorization server's token-introspection endpoint, and reports who the token was issued for (its `aud`) in `AccessToken.resource`. That code is yours; the SDK only calls it.
+* This one looks the token up in a table; each entry records the resource it was issued for. A real one verifies a JWT signature or calls the authorization server's token-introspection endpoint, and reports who the token was issued for (its `aud`) in `AccessToken.resource`. That code is yours; the SDK only calls it.
 * `token_verifier=` and `auth=` always travel together. Pass one without the other and `MCPServer(...)` raises a `ValueError` before it ever serves a request.
 
 `AuthSettings` is the public face of your resource server:
 
 * `issuer_url`: the authorization server that issues your tokens.
 * `resource_server_url`: the public URL of this MCP endpoint. It names *which* resource a token is for, and it's where the discovery document lives.
 * `required_scopes`: every token must carry all of them.
-* `validate_token_resource`: refuse any token whose `AccessToken.resource` is not `resource_server_url`. Off by default.
+* `validate_token_resource`: refuse any token whose `AccessToken.resource` is not `resource_server_url`. Leaving it unset warns (`MCPDeprecationWarning`) and behaves as `False`; 3.0 makes `True` the default.
   * Turn it on when your authorization server binds tokens to the `resource` the client requested, which MCP clients always send. Keep `resource_server_url` the exact URL clients connect to.
   * Leave it off when your authorization server uses its own audience identifiers (an Auth0 API identifier, an Entra application ID) and check `aud` in your verifier instead, returning `None` for a token that isn't for this server.
   * If `aud` is a list, put the entry that equals `resource_server_url` in `resource`.
@@ -90,7 +90,7 @@ This document is how a client that has never heard of your server finds its way
 
 Inside any handler, **`get_access_token()`** is the `AccessToken` your verifier returned for the current request:
 
-```python title="server.py" hl_lines="4 32-35"
+```python title="server.py" hl_lines="4 35-38"
 --8<-- "docs_src/authorization/tutorial002.py"
 ```
 

docs_src/authorization/tutorial001.py

@@ -4,8 +4,10 @@
 from mcp.server.auth.provider import AccessToken, TokenVerifier
 from mcp.server.auth.settings import AuthSettings
 
+RESOURCE = "http://127.0.0.1:8000/mcp"
+
 KNOWN_TOKENS = {
-    "alice-token": AccessToken(token="alice-token", client_id="alice", scopes=["notes:read"]),
+    "alice-token": AccessToken(token="alice-token", client_id="alice", scopes=["notes:read"], resource=RESOURCE),
 }
 
 
@@ -19,8 +21,9 @@ async def verify_token(self, token: str) -> AccessToken | None:
     token_verifier=StaticTokenVerifier(),
     auth=AuthSettings(
         issuer_url=AnyHttpUrl("https://auth.example.com"),
-        resource_server_url=AnyHttpUrl("http://127.0.0.1:8000/mcp"),
+        resource_server_url=AnyHttpUrl(RESOURCE),
         required_scopes=["notes:read"],
+        validate_token_resource=True,
     ),
 )
 

docs_src/authorization/tutorial002.py

@@ -5,8 +5,10 @@
 from mcp.server.auth.provider import AccessToken, TokenVerifier
 from mcp.server.auth.settings import AuthSettings
 
+RESOURCE = "http://127.0.0.1:8000/mcp"
+
 KNOWN_TOKENS = {
-    "alice-token": AccessToken(token="alice-token", client_id="alice", scopes=["notes:read"]),
+    "alice-token": AccessToken(token="alice-token", client_id="alice", scopes=["notes:read"], resource=RESOURCE),
 }
 
 
@@ -20,8 +22,9 @@ async def verify_token(self, token: str) -> AccessToken | None:
     token_verifier=StaticTokenVerifier(),
     auth=AuthSettings(
         issuer_url=AnyHttpUrl("https://auth.example.com"),
-        resource_server_url=AnyHttpUrl("http://127.0.0.1:8000/mcp"),
+        resource_server_url=AnyHttpUrl(RESOURCE),
         required_scopes=["notes:read"],
+        validate_token_resource=True,
     ),
 )
 

examples/snippets/servers/oauth_server.py

@@ -24,8 +24,9 @@ async def verify_token(self, token: str) -> AccessToken | None:
     # Auth settings for RFC 9728 Protected Resource Metadata
     auth=AuthSettings(
         issuer_url=AnyHttpUrl("https://auth.example.com"),  # Authorization Server URL
-        resource_server_url=AnyHttpUrl("http://localhost:3001"),  # This server's URL
+        resource_server_url=AnyHttpUrl("http://localhost:3001/mcp"),  # This server's URL
         required_scopes=["user"],
+        validate_token_resource=True,
     ),
 )
 

examples/stories/_shared/auth.py

@@ -169,4 +169,5 @@ def auth_settings(
         required_scopes=scopes,
         client_registration_options=ClientRegistrationOptions(enabled=True, valid_scopes=scopes, default_scopes=scopes),
         identity_assertion_enabled=identity_assertion_enabled,
+        validate_token_resource=True,
     )

examples/stories/bearer_auth/server.py

@@ -28,6 +28,7 @@ async def verify_token(self, token: str) -> AccessToken | None:
             client_id="demo-client",
             scopes=[REQUIRED_SCOPE],
             expires_at=int(time.time()) + 3600,
+            resource=RESOURCE_URL,
             subject="demo-user",
         )
 
@@ -40,6 +41,7 @@ def build_app() -> Starlette:
             issuer_url=AnyHttpUrl(ISSUER),
             resource_server_url=AnyHttpUrl(RESOURCE_URL),
             required_scopes=[REQUIRED_SCOPE],
+            validate_token_resource=True,
         ),
     )
 

examples/stories/bearer_auth/server_lowlevel.py

@@ -46,6 +46,7 @@ async def call_tool(ctx: ServerRequestContext[Any], params: types.CallToolReques
             issuer_url=AnyHttpUrl(ISSUER),
             resource_server_url=AnyHttpUrl(RESOURCE_URL),
             required_scopes=[REQUIRED_SCOPE],
+            validate_token_resource=True,
         ),
         token_verifier=StaticTokenVerifier(),
         transport_security=NO_DNS_REBIND,

examples/stories/oauth_client_credentials/server.py

@@ -66,7 +66,14 @@ async def token_endpoint(request: Request) -> JSONResponse:
         if creds != f"{DEMO_CLIENT_ID}:{DEMO_CLIENT_SECRET}":
             return JSONResponse({"error": "invalid_client"}, status_code=401)
         access = f"access_{secrets.token_hex(16)}"
-        issued[access] = AccessToken(token=access, client_id=DEMO_CLIENT_ID, scopes=[DEMO_SCOPE], expires_at=None)
+        resource = form.get("resource")  # RFC 8707: bind the token to the resource the client asked for
+        issued[access] = AccessToken(
+            token=access,
+            client_id=DEMO_CLIENT_ID,
+            scopes=[DEMO_SCOPE],
+            expires_at=None,
+            resource=resource if isinstance(resource, str) else None,
+        )
         body = OAuthToken(access_token=access, token_type="Bearer", expires_in=3600, scope=DEMO_SCOPE)
         return JSONResponse(body.model_dump(exclude_none=True), headers={"cache-control": "no-store"})
 

examples/stories/oauth_client_credentials/server_lowlevel.py

@@ -63,7 +63,14 @@ async def token_endpoint(request: Request) -> JSONResponse:
         if creds != f"{DEMO_CLIENT_ID}:{DEMO_CLIENT_SECRET}":
             return JSONResponse({"error": "invalid_client"}, status_code=401)
         access = f"access_{secrets.token_hex(16)}"
-        issued[access] = AccessToken(token=access, client_id=DEMO_CLIENT_ID, scopes=[DEMO_SCOPE], expires_at=None)
+        resource = form.get("resource")  # RFC 8707: bind the token to the resource the client asked for
+        issued[access] = AccessToken(
+            token=access,
+            client_id=DEMO_CLIENT_ID,
+            scopes=[DEMO_SCOPE],
+            expires_at=None,
+            resource=resource if isinstance(resource, str) else None,
+        )
         body = OAuthToken(access_token=access, token_type="Bearer", expires_in=3600, scope=DEMO_SCOPE)
         return JSONResponse(body.model_dump(exclude_none=True), headers={"cache-control": "no-store"})