Adds an opt-in AuthSettings.validate_token_resource. When set, the bearer gate only accepts a token that the TokenVerifier reports as issued for resource_server_url (via AccessToken.resource); a token reporting another resource, or none, gets the same 401 as an unrecognized token. Leaving it unset on a resource server emits an MCPDeprecationWarning and behaves as off; 3.0 makes it the default there.

Motivation and Context

The resource-server gate checks scopes and expiry but has never compared the token's RFC 8707 resource indicator with the server's own identifier; the interaction suite records this as the hosting:auth:aud-validation divergence. In practice that comparison was left to each TokenVerifier, without the docs or the protocol docstring saying so.

This does two things:

• Documents the contract. TokenVerifier.verify_token and docs/run/authorization.md now say to put the token's audience in AccessToken.resource, and that otherwise confirming the token was issued for this server is the verifier's job.
• Adds the option for deployments whose authorization server binds tokens to the resource the client requested (which is what MCP clients send). It isn't enforced by default because AccessToken.resource gets populated in lots of ways today (IdP-specific audience identifiers, for instance), and doing so unconditionally would reject valid tokens in those setups; instead an unset value warns so each deployment chooses True or False once. RefreshToken gains an optional resource so providers can carry the binding through the refresh grant.

The comparison is URL equality with a trailing slash tolerated; both sides go through AnyHttpUrl so host case and an explicit default port don't matter. It lives in BearerAuthBackend (new keyword-only resource_server_url) so a refused token never reaches get_access_token() or custom routes, and a refusal logs both values at warning level.

How Has This Been Tested?

• Unit table for BearerAuthBackend with and without resource_server_url (match, trailing slash, case/port spelling, parent/child/sibling path, other origin, non-URL value, no resource), plus the AuthSettings validation.
• Interaction suite: the bearer tests enable the option (other-resource and no-resource tokens are answered 401, a token for this resource is served); the requirement keeps a note that it's off by default.
• End to end under uvicorn with an introspection-backed verifier over Streamable HTTP: option on, a token for another resource gets 401 and one for this server 200; option off, behaviour unchanged.
• ./scripts/test, ruff, pyright.

Breaking Changes

None. Unset behaves as off (with the deprecation warning); BearerAuthBackend(verifier) and existing verifiers behave as before. Setting it to True without a resource_server_url raises at construction.

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

The docs tutorials, the bearer_auth / oauth_client_credentials stories, the oauth_server snippet and the simple-auth example set the option explicitly and issue tokens bound to their resource URL; docs/deprecated.md lists the warning.

AI Disclaimer