Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Enforce component authorization and bind OAuth credentials to an issuer (#5933)

nate nowack85df42fbf2aa
diff --git a/docs/clients/auth/client-credentials.mdx b/docs/clients/auth/client-credentials.mdx
index 382a5d8e9..9212a5107 100644
--- a/docs/clients/auth/client-credentials.mdx
+++ b/docs/clients/auth/client-credentials.mdx
@@ -21,7 +21,7 @@ FastMCP provides two providers for this, both implementing the `httpx2.Auth` int
The common case is a pre-registered client with an ID and a secret. Use `ClientCredentialsOAuthProvider` and pass it to the `auth` parameter of your `Client` or transport:
-```python {2, 4-8, 10}
+```python {2, 4-9, 11}
from fastmcp import Client
from fastmcp.client.auth import ClientCredentialsOAuthProvider
@@ -29,13 +29,18 @@ auth = ClientCredentialsOAuthProvider(
client_id="my-client-id",
client_secret="my-client-secret",
scopes=["read", "write"],
+ issuer="https://auth.example.com",
)
async with Client("https://example.com/mcp", auth=auth) as client:
await client.list_tools()
```
-The provider discovers the authorization server, exchanges the credentials for an access token, and caches the token in memory for the life of the client. When the token expires it is re-acquired automatically on the next request. Because re-acquiring a token is a single non-interactive request, tokens are held in memory by default with no warning β€” unlike the interactive `OAuth` flow, losing the cache on restart costs nothing.
+The provider discovers the authorization server, exchanges the credentials for an access token, and caches the token in memory for the life of the client. When the token expires it is re-acquired automatically on the next request. Because re-acquiring a token is a single non-interactive request, tokens are held in memory by default with no warning β€” unlike the interactive `OAuth` flow, losing the cache on restart costs nothing. Cached tokens are isolated by client ID, requested scopes, and configured issuer, so changing `issuer` acquires a new token.
+
+Always pass `issuer`, the issuer identifier of the authorization server that issued your credentials. Without it, the MCP server decides which authorization server receives them, so a malicious or compromised server can advertise its own authorization server and collect your client secret or signed assertion. With `issuer` set, the provider only sends credentials to an authorization server whose discovered metadata names that issuer, and otherwise stops with an `OAuthFlowError`.
+
+Omitting `issuer` remains supported for compatibility and emits an `MCPDeprecationWarning`; upgrading alone does not bind existing credentials. Set `issuer` when upgrading, and rotate credentials that may already have been sent to an untrusted server.
### `ClientCredentialsOAuthProvider` Parameters
@@ -44,6 +49,7 @@ The provider discovers the authorization server, exchanges the credentials for a
- **`client_secret`** (`str`, required): The OAuth client secret.
- **`scopes`** (`str | list[str]`, optional): Scopes to request, as a space-separated string or a list.
- **`token_endpoint_auth_method`** (`"client_secret_basic" | "client_secret_post"`, optional): How the credentials are presented to the token endpoint. Defaults to `"client_secret_basic"` (an HTTP Basic `Authorization` header); use `"client_secret_post"` to send them in the request body instead.
+- **`issuer`** (`str`, optional): <VersionBadge version="4.1.2" /> The issuer identifier of the authorization server that issued these credentials. Credentials are only sent to an authorization server whose discovered metadata names this issuer. Always set it.
- **`token_storage`** (`AsyncKeyValue`, optional): A key-value store for the acquired token. Defaults to in-memory storage.
## Private Key JWT
@@ -52,7 +58,7 @@ Some authorization servers require the client to prove its identity with a signe
For a locally signed assertion, build the callback with `SignedJWTParameters`:
-```python {4-7, 9, 11-15, 17-20, 22}
+```python {4-7, 9, 11-15, 17-21, 23}
from pathlib import Path
from fastmcp import Client
@@ -72,6 +78,7 @@ jwt_params = SignedJWTParameters(
auth = PrivateKeyJWTOAuthProvider(
client_id="my-client-id",
assertion_provider=jwt_params.create_assertion_provider(),
+ issuer="https://auth.example.com",
)
async with Client("https://example.com/mcp", auth=auth) as client:
@@ -86,4 +93,5 @@ If you already have a JWT from an identity provider, wrap it with `static_assert
- **`client_id`** (`str`, required): The OAuth client ID.
- **`assertion_provider`** (`Callable[[str], Awaitable[str]]`, required): Async callback that receives the authorization server's issuer identifier and returns a signed JWT assertion.
- **`scopes`** (`str | list[str]`, optional): Scopes to request, as a space-separated string or a list.
+- **`issuer`** (`str`, optional): <VersionBadge version="4.1.2" /> The issuer identifier of the authorization server that issued these credentials. Credentials are only sent to an authorization server whose discovered metadata names this issuer. Always set it.
- **`token_storage`** (`AsyncKeyValue`, optional): A key-value store for the acquired token. Defaults to in-memory storage.
diff --git a/fastmcp_slim/fastmcp/client/auth/client_credentials.py b/fastmcp_slim/fastmcp/client/auth/client_credentials.py
index 6cdcf6f1a..41a70c577 100644
--- a/fastmcp_slim/fastmcp/client/auth/client_credentials.py
+++ b/fastmcp_slim/fastmcp/client/auth/client_credentials.py
@@ -61,17 +61,13 @@ def _normalize_scopes(scopes: str | list[str] | None) -> str | None:
return scopes
-def _cache_namespace(client_id: str, scopes: str | None) -> str:
- """Namespace cached tokens by both client identity and requested scopes.
-
- Two providers that differ in either their ``client_id`` or their requested
- scopes must not share cached tokens: a token issued for one client or one
- scope set is not interchangeable with another. Hashing a canonical
- ``(client_id, scopes)`` pair keeps the namespace unambiguous regardless of the
- characters either value contains.
- """
- identity = json.dumps([client_id, scopes], separators=(",", ":"))
- return hashlib.sha256(identity.encode()).hexdigest()
+def _cache_namespace(client_id: str, scopes: str | None, issuer: str | None) -> str:
+ """Isolate tokens by client, requested scopes, and configured issuer."""
+ identity = [client_id, scopes]
+ if issuer is not None:
+ identity.append(issuer)
+ encoded = json.dumps(identity, separators=(",", ":"))
+ return hashlib.sha256(encoded.encode()).hexdigest()
def _resolve_token_storage(
@@ -79,6 +75,7 @@ def _resolve_token_storage(
mcp_url: str,
client_id: str,
scopes: str | None,
+ issuer: str | None,
) -> TokenStorageAdapter:
"""Wrap a token store in the FastMCP adapter, defaulting to in-memory.
@@ -86,15 +83,15 @@ def _resolve_token_storage(
in-memory storage: re-acquiring a token is a single non-interactive request,
so losing the cache on restart is cheap rather than disruptive.
- The cache is namespaced by client identity and requested scopes so that
- providers with different credentials or scope sets can share one store against
+ The cache is namespaced by client identity, requested scopes, and issuer so
+ providers with different identities can share one store against
the same MCP endpoint without overwriting each other's tokens.
"""
store = token_storage or MemoryStore()
return TokenStorageAdapter(
async_key_value=store,
server_url=mcp_url,
- cache_namespace=_cache_namespace(client_id, scopes),
+ cache_namespace=_cache_namespace(client_id, scopes, issuer),
)
@@ -111,7 +108,10 @@ async def _restore_token_expiry(context: OAuthContext) -> None:
The inherited initializer reloads the stored token but not its expiry, so a
provider recreated with persistent storage would treat an already-expired
token as still valid. Reading the absolute expiry back keeps `is_token_valid`
- honest, prompting a fresh token request when the stored one has expired.
+ honest. Cached refresh tokens are discarded so M2M authorization rediscovers
+ the issuer when the access token expires, even if it was valid when loaded.
+ Authorization server metadata is not persisted, so the inherited refresh
+ fallback would otherwise send credentials to the MCP server itself.
The restore is skipped unless the reloaded token itself declares an
`expires_in`. A token whose response omitted `expires_in` (``None``) is
@@ -122,6 +122,8 @@ async def _restore_token_expiry(context: OAuthContext) -> None:
"""
storage = context.storage
tokens = context.current_tokens
+ if tokens is not None and tokens.refresh_token is not None:
+ context.current_tokens = tokens.model_copy(update={"refresh_token": None})
if tokens is None or tokens.expires_in is None:
return
if not isinstance(storage, TokenStorageAdapter):
@@ -179,6 +181,7 @@ class ClientCredentialsOAuthProvider(_SDKClientCredentialsOAuthProvider):
client_id="my-client-id",
client_secret="my-client-secret",
scopes=["read", "write"],
+ issuer="https://auth.example.com",
)
async with Client("https://example.com/mcp", auth=auth) as client:
@@ -198,6 +201,7 @@ class ClientCredentialsOAuthProvider(_SDKClientCredentialsOAuthProvider):
token_endpoint_auth_method: Literal[
"client_secret_basic", "client_secret_post"
] = "client_secret_basic",
+ issuer: str | None = None,
token_storage: AsyncKeyValue | None = None,
) -> None:
"""Initialize a client_credentials OAuth provider.
@@ -214,6 +218,11 @@ class ClientCredentialsOAuthProvider(_SDKClientCredentialsOAuthProvider):
token endpoint. "client_secret_basic" (default) sends them in an
HTTP Basic ``Authorization`` header; "client_secret_post" sends them
in the request body.
+ issuer: The issuer identifier of the authorization server that issued
+ these credentials. Token requests are only built from discovered
+ authorization server metadata whose issuer matches; otherwise the flow
+ stops with `OAuthFlowError`. Without it, the MCP server decides which
+ authorization server receives the credentials, so always pass it.
token_storage: An AsyncKeyValue-compatible token store. Tokens are kept
in memory if not provided.
"""
@@ -221,6 +230,7 @@ class ClientCredentialsOAuthProvider(_SDKClientCredentialsOAuthProvider):
self._client_secret = client_secret
self._scopes = _normalize_scopes(scopes)
self._token_endpoint_auth_method = token_endpoint_auth_method
+ self._issuer = issuer
self._token_storage = token_storage
self._bound = False
@@ -240,12 +250,17 @@ class ClientCredentialsOAuthProvider(_SDKClientCredentialsOAuthProvider):
super().__init__(
server_url=mcp_url,
storage=_resolve_token_storage(
- self._token_storage, mcp_url, self._client_id, self._scopes
+ self._token_storage,
+ mcp_url,
+ self._client_id,
+ self._scopes,
+ self._issuer,
),
client_id=self._client_id,
client_secret=self._client_secret,
token_endpoint_auth_method=self._token_endpoint_auth_method,
scope=self._scopes,
+ issuer=self._issuer,
)
self._bound = True
@@ -309,6 +324,7 @@ class PrivateKeyJWTOAuthProvider(_SDKPrivateKeyJWTOAuthProvider):
auth = PrivateKeyJWTOAuthProvider(
client_id="my-client-id",
assertion_provider=jwt_params.create_assertion_provider(),
+ issuer="https://auth.example.com",
)
async with Client("https://example.com/mcp", auth=auth) as client:
@@ -325,6 +341,7 @@ class PrivateKeyJWTOAuthProvider(_SDKPrivateKeyJWTOAuthProvider):
client_id: str,
assertion_provider: Callable[[str], Awaitable[str]],
scopes: str | list[str] | None = None,
+ issuer: str | None = None,
token_storage: AsyncKeyValue | None = None,
) -> None:
"""Initialize a private_key_jwt OAuth provider.
@@ -342,12 +359,18 @@ class PrivateKeyJWTOAuthProvider(_SDKPrivateKeyJWTOAuthProvider):
federation.
scopes: OAuth scopes to request, as a space-separated string or a list
of strings.
+ issuer: The issuer identifier of the authorization server that issued
+ these credentials. Token requests are only built from discovered
+ authorization server metadata whose issuer matches; otherwise the flow
+ stops with `OAuthFlowError`. Without it, the MCP server decides which
+ authorization server receives the credentials, so always pass it.
token_storage: An AsyncKeyValue-compatible token store. Tokens are kept
in memory if not provided.
"""
self._client_id = client_id
self._assertion_provider = assertion_provider
self._scopes = _normalize_scopes(scopes)
+ self._issuer = issuer
self._token_storage = token_storage
self._bound = False
@@ -367,11 +390,16 @@ class PrivateKeyJWTOAuthProvider(_SDKPrivateKeyJWTOAuthProvider):
super().__init__(
server_url=mcp_url,
storage=_resolve_token_storage(
- self._token_storage, mcp_url, self._client_id, self._scopes
+ self._token_storage,
+ mcp_url,
+ self._client_id,
+ self._scopes,
+ self._issuer,
),
client_id=self._client_id,
assertion_provider=self._assertion_provider,
scope=self._scopes,
+ issuer=self._issuer,
)
self._bound = True
diff --git a/fastmcp_slim/fastmcp/server/server.py b/fastmcp_slim/fastmcp/server/server.py
index 5cd90910d..0aea063c2 100644
--- a/fastmcp_slim/fastmcp/server/server.py
+++ b/fastmcp_slim/fastmcp/server/server.py
@@ -234,14 +234,16 @@ LifespanCallable = Callable[
]
-async def _tool_auth_allows(tool: Tool) -> bool:
- """Whether the tool's own `auth` check admits the current request."""
+async def _component_auth_allows(
+ component: Tool | Resource | ResourceTemplate | Prompt,
+) -> bool:
+ """Whether the component's own `auth` check admits the current request."""
skip_auth, token = _get_auth_context()
- if skip_auth or tool.auth is None:
+ if skip_auth or component.auth is None:
return True
- ctx = AuthContext(token=token, component=tool)
+ ctx = AuthContext(token=token, component=component)
try:
- return await run_auth_checks(tool.auth, ctx)
+ return await run_auth_checks(component.auth, ctx)
except AuthorizationError:
return False
@@ -869,7 +871,7 @@ class FastMCP(
claimed = {tool.name for tool in injected}
tools = [*injected, *(t for t in tools if t.name not in claimed)]
- return [tool for tool in tools if await _tool_auth_allows(tool)]
+ return [tool for tool in tools if await _component_auth_allows(tool)]
async def _get_tool(
self, name: str, version: VersionSpec | None = None
@@ -891,11 +893,11 @@ class FastMCP(
return None
# Component auth - return None if unauthorized (consistent with list filtering)
- return tool if await _tool_auth_allows(tool) else None
+ return tool if await _component_auth_allows(tool) else None
async def _check_hashed_target(self, tool: Tool) -> Tool | None:
"""Check auth on the found tool, as `_get_tool()` does for a name."""
- return tool if await _tool_auth_allows(tool) else None
+ return tool if await _component_auth_allows(tool) else None
async def get_tool(
self, name: str, version: VersionSpec | None = None
@@ -928,7 +930,7 @@ class FastMCP(
else None
)
if injected is not None:
- return injected if await _tool_auth_allows(injected) else None
+ return injected if await _component_auth_allows(injected) else None
tool = await super().get_tool(name, version)
if tool is None:
@@ -936,7 +938,9 @@ class FastMCP(
# Apply session transforms to single item
tools = await apply_session_transforms([tool])
- if tools and is_enabled(tools[0]):
+ # Transforms can change what `auth` sees (a tag, for one), so the check made
+ # on the pre-transform component is not enough.
+ if tools and is_enabled(tools[0]) and await _component_auth_allows(tools[0]):
return tools[0]
# The highest version is disabled. If an explicit version was
@@ -955,7 +959,7 @@ class FastMCP(
all_tools = list(await apply_session_transforms(all_tools))
enabled = [t for t in all_tools if is_enabled(t)]
- authorized = [t for t in enabled if await _tool_auth_allows(t)]
+ authorized = [t for t in enabled if await _component_auth_allows(t)]
if not authorized:
return None
@@ -1027,22 +1031,18 @@ class FastMCP(
version: Version filter (None returns highest version).
Returns:
- The resource if found and authorized, None if not found or unauthorized.
+ The resource if found and authorized, None if not found.
+
+ Raises:
+ AuthorizationError: The resource exists but access is denied.
"""
# Get resource from AggregateProvider (handles aggregation and namespacing)
resource = await super()._get_resource(uri, version)
if resource is None:
return None
- # Component auth - return None if unauthorized (consistent with list filtering)
- skip_auth, token = _get_auth_context()
- if not skip_auth and resource.auth is not None:
- ctx = AuthContext(token=token, component=resource)
- try:
- if not await run_auth_checks(resource.auth, ctx):
- return None
- except AuthorizationError:
- return None
+ if not await _component_auth_allows(resource):
+ raise AuthorizationError(f"Access denied to resource: {uri!r}")
return resource
@@ -1075,13 +1075,20 @@ class FastMCP(
Also reports whether a concrete resource exists at `uri` at all, so
reads can tell a hidden resource apart from a missing one.
"""
- resource = await super().get_resource(uri, version)
+ try:
+ resource = await super().get_resource(uri, version)
+ except AuthorizationError:
+ return None, True
if resource is None:
return None, False
# Apply session transforms to single item
resources = await apply_session_transforms([resource])
- if resources and is_enabled(resources[0]):
+ if (
+ resources
+ and is_enabled(resources[0])
+ and await _component_auth_allows(resources[0])
+ ):
return resources[0], True
if version is not None:
@@ -1213,7 +1220,13 @@ class FastMCP(
# Apply session transforms to single item
templates = await apply_session_transforms([template])
- if templates and is_enabled(templates[0]):
+ # Transforms can change what `auth` sees (a tag, for one), so the check made
+ # on the pre-transform component is not enough.
+ if (
+ templates
+ and is_enabled(templates[0])
+ and await _component_auth_allows(templates[0])
+ ):
return templates[0]
if version is not None:
@@ -1339,7 +1352,13 @@ class FastMCP(
# Apply session transforms to single item
prompts = await apply_session_transforms([prompt])
- if prompts and is_enabled(prompts[0]):
+ # Transforms can change what `auth` sees (a tag, for one), so the check made
+ # on the pre-transform component is not enough.
+ if (
+ prompts
+ and is_enabled(prompts[0])
+ and await _component_auth_allows(prompts[0])
+ ):
return prompts[0]
if version is not None:
diff --git a/fastmcp_slim/pyproject.toml b/fastmcp_slim/pyproject.toml
index dc4b12196..8f5b3b136 100644
--- a/fastmcp_slim/pyproject.toml
+++ b/fastmcp_slim/pyproject.toml
@@ -86,7 +86,7 @@ mcp = [
# client auth) requires it, and all FastMCP-owned HTTP (server auth provider
# upstream calls, OpenAPI provider, version check, etc.) uses it too.
"httpx2>=2.5.0",
- "mcp>=2.0.0,<3.0.0",
+ "mcp>=2.2.0,<3.0.0",
"opentelemetry-api>=1.28.0",
# starlette floor: transitive via mcp (which only requires >=0.27).
# Pin past CVE-2026-48710, which was patched in 1.0.1.
diff --git a/tests/client/auth/test_client_credentials.py b/tests/client/auth/test_client_credentials.py
index 59a0c57cd..db0fdf433 100644
--- a/tests/client/auth/test_client_credentials.py
+++ b/tests/client/auth/test_client_credentials.py
@@ -9,6 +9,7 @@ endpoint, exactly as httpx would while running the auth flow.
"""
import base64
+import time
import warnings
from collections.abc import Callable
from contextlib import aclosing
@@ -18,7 +19,7 @@ import httpx2
import jwt
import pytest
from key_value.aio.stores.memory import MemoryStore
-from mcp.client.auth import OAuthTokenError
+from mcp.client.auth import OAuthFlowError, OAuthTokenError
from mcp.shared.auth import OAuthToken
from fastmcp.client import Client
@@ -301,6 +302,48 @@ class TestClientCredentialsFlow:
class TestTokenCacheIsolation:
"""Cached tokens are namespaced by client identity, not just server URL."""
+ @pytest.mark.parametrize("provider_type", ["secret", "jwt"])
+ @pytest.mark.parametrize("previous_issuer", [None, "https://previous.example.com"])
+ async def test_changed_issuer_does_not_reuse_cached_token(
+ self, provider_type, previous_issuer
+ ):
+ store = MemoryStore()
+
+ def make_provider(issuer):
+ if provider_type == "jwt":
+ return PrivateKeyJWTOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ assertion_provider=static_assertion_provider("assertion"),
+ issuer=issuer,
+ token_storage=store,
+ )
+ return ClientCredentialsOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ client_secret="secret",
+ issuer=issuer,
+ token_storage=store,
+ )
+
+ previous = make_provider(previous_issuer)
+ await previous.context.storage.set_tokens(
+ OAuthToken(access_token="previous", token_type="Bearer", expires_in=3600)
+ )
+ responder, captured = make_m2m_responder(
+ token_response={"access_token": "current", "token_type": "Bearer"}
+ )
+ async with httpx2.AsyncClient(
+ auth=make_provider(AUTH_SERVER_URL),
+ transport=httpx2.MockTransport(responder),
+ ) as client:
+ assert (await client.post(SERVER_URL)).status_code == 200
+
+ assert captured["final_request"].headers["Authorization"] == "Bearer current"
+ assert str(captured["token_request"].url) == f"{AUTH_SERVER_URL}/token"
+ previous_token = await previous.context.storage.get_tokens()
+ assert previous_token is not None and previous_token.access_token == "previous"
+
async def test_distinct_client_ids_do_not_share_cached_tokens(self):
"""Two providers with different client_ids sharing one store against the
same endpoint each retain their own token instead of clobbering one
@@ -685,3 +728,294 @@ def test_assertion_provider_signs_expected_audience():
# The assertion is a JWT whose audience is exactly the requested issuer.
claims = jwt.decode(assertion, options={"verify_signature": False})
assert claims["aud"] == "https://issuer.example.com"
+
+
+class TestIssuerBinding:
+ """With `issuer` set, credentials only go to that authorization server."""
+
+ TOKEN_RESPONSE = {"access_token": "T", "token_type": "Bearer"}
+
+ async def test_client_secret_not_sent_to_other_issuer(self):
+ provider = ClientCredentialsOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ client_secret="secret",
+ issuer=AUTH_SERVER_URL,
+ )
+ responder, captured = make_m2m_responder(
+ token_response=self.TOKEN_RESPONSE,
+ auth_server_url="https://attacker.example.com",
+ )
+
+ with pytest.raises(OAuthFlowError, match="issuer"):
+ await drive_auth_flow(provider, responder)
+ assert "token_request" not in captured
+
+ async def test_client_secret_sent_to_configured_issuer(self):
+ provider = ClientCredentialsOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ client_secret="secret",
+ issuer=AUTH_SERVER_URL,
+ )
+ responder, captured = make_m2m_responder(token_response=self.TOKEN_RESPONSE)
+
+ requests = await drive_auth_flow(provider, responder)
+
+ assert str(captured["token_request"].url) == f"{AUTH_SERVER_URL}/token"
+ assert requests[-1].headers["Authorization"] == "Bearer T"
+
+ async def test_assertion_not_minted_for_other_issuer(self):
+ audiences: list[str] = []
+
+ async def assertion_provider(audience: str) -> str:
+ audiences.append(audience)
+ return "assertion"
+
+ provider = PrivateKeyJWTOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ assertion_provider=assertion_provider,
+ issuer=AUTH_SERVER_URL,
+ )
+ responder, captured = make_m2m_responder(
+ token_response=self.TOKEN_RESPONSE,
+ auth_server_url="https://attacker.example.com",
+ )
+
+ with pytest.raises(OAuthFlowError, match="issuer"):
+ await drive_auth_flow(provider, responder)
+ assert "token_request" not in captured
+ assert audiences == []
+
+ async def test_assertion_sent_to_configured_issuer(self):
+ audiences: list[str] = []
+
+ async def assertion_provider(audience: str) -> str:
+ audiences.append(audience)
+ return "assertion"
+
+ provider = PrivateKeyJWTOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ assertion_provider=assertion_provider,
+ issuer=AUTH_SERVER_URL,
+ )
+ responder, captured = make_m2m_responder(token_response=self.TOKEN_RESPONSE)
+
+ requests = await drive_auth_flow(provider, responder)
+
+ assert audiences == [AUTH_SERVER_URL]
+ assert str(captured["token_request"].url) == f"{AUTH_SERVER_URL}/token"
+ assert requests[-1].headers["Authorization"] == "Bearer T"
+
+ @pytest.mark.parametrize("provider_type", ["secret_basic", "secret_post", "jwt"])
+ @pytest.mark.parametrize("metadata_case", ["matching", "mismatch", "forged"])
+ async def test_expired_cached_token_rediscovers_issuer(
+ self, provider_type, metadata_case
+ ):
+ store = MemoryStore()
+ audiences: list[str] = []
+ requests: list[httpx2.Request] = []
+
+ async def assertion_provider(audience: str) -> str:
+ audiences.append(audience)
+ return "assertion"
+
+ def make_provider():
+ if provider_type == "jwt":
+ return PrivateKeyJWTOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ assertion_provider=assertion_provider,
+ issuer=AUTH_SERVER_URL,
+ token_storage=store,
+ )
+ return ClientCredentialsOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ client_secret="secret",
+ token_endpoint_auth_method=(
+ "client_secret_basic"
+ if provider_type == "secret_basic"
+ else "client_secret_post"
+ ),
+ issuer=AUTH_SERVER_URL,
+ token_storage=store,
+ )
+
+ seed = make_provider()
+ await seed.context.storage.set_tokens(
+ OAuthToken(
+ access_token="expired",
+ token_type="Bearer",
+ expires_in=-1,
+ refresh_token="refresh-credential",
+ )
+ )
+ auth_server = (
+ AUTH_SERVER_URL
+ if metadata_case == "matching"
+ else "https://attacker.example.com"
+ )
+ respond, captured = make_m2m_responder(
+ token_response=self.TOKEN_RESPONSE, auth_server_url=auth_server
+ )
+
+ def responder(request: httpx2.Request) -> httpx2.Response:
+ requests.append(request)
+ if str(request.url) == "https://mcp.example.com/token":
+ return httpx2.Response(400, json={"error": "invalid_grant"})
+ response = respond(request)
+ if metadata_case == "forged" and request.url.path.startswith(
+ "/.well-known/oauth-authorization-server"
+ ):
+ metadata = response.json()
+ metadata["issuer"] = AUTH_SERVER_URL
+ return httpx2.Response(200, json=metadata)
+ return response
+
+ provider = make_provider()
+ async with httpx2.AsyncClient(
+ auth=provider, transport=httpx2.MockTransport(responder)
+ ) as client:
+ if metadata_case == "matching":
+ assert (await client.post(SERVER_URL)).status_code == 200
+ else:
+ with pytest.raises(OAuthFlowError, match="issuer"):
+ await client.post(SERVER_URL)
+
+ assert str(requests[0].url) == SERVER_URL
+ assert all(b"refresh-credential" not in request.content for request in requests)
+ if metadata_case == "matching":
+ token_request = captured["token_request"]
+ assert str(token_request.url) == f"{AUTH_SERVER_URL}/token"
+ assert form_body(token_request)["grant_type"] == "client_credentials"
+ assert audiences == ([AUTH_SERVER_URL] if provider_type == "jwt" else [])
+ else:
+ assert "token_request" not in captured
+ assert audiences == []
+ assert all("Authorization" not in request.headers for request in requests)
+
+ @pytest.mark.parametrize("provider_type", ["secret", "jwt"])
+ @pytest.mark.parametrize("metadata_case", ["forged", "missing"])
+ async def test_untrusted_metadata_cannot_supply_token_endpoint(
+ self, provider_type, metadata_case
+ ):
+ audiences: list[str] = []
+ requests: list[httpx2.Request] = []
+
+ async def assertion_provider(audience: str) -> str:
+ audiences.append(audience)
+ return "assertion"
+
+ if provider_type == "secret":
+ provider = ClientCredentialsOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ client_secret="secret",
+ issuer=AUTH_SERVER_URL,
+ )
+ else:
+ provider = PrivateKeyJWTOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ assertion_provider=assertion_provider,
+ issuer=AUTH_SERVER_URL,
+ )
+ respond, captured = make_m2m_responder(
+ token_response=self.TOKEN_RESPONSE,
+ auth_server_url="https://attacker.example.com",
+ )
+
+ def responder(request: httpx2.Request) -> httpx2.Response:
+ requests.append(request)
+ response = respond(request)
+ if request.url.path.startswith(
+ (
+ "/.well-known/oauth-authorization-server",
+ "/.well-known/openid-configuration",
+ )
+ ):
+ if metadata_case == "missing":
+ return httpx2.Response(404)
+ metadata = response.json()
+ metadata["issuer"] = AUTH_SERVER_URL
+ return httpx2.Response(200, json=metadata)
+ return response
+
+ async with httpx2.AsyncClient(
+ auth=provider, transport=httpx2.MockTransport(responder)
+ ) as client:
+ with pytest.raises(OAuthFlowError, match="issuer"):
+ await client.post(SERVER_URL)
+
+ assert "token_request" not in captured
+ assert audiences == []
+ assert all("Authorization" not in request.headers for request in requests)
+
+ @pytest.mark.parametrize("provider_type", ["secret", "jwt"])
+ @pytest.mark.parametrize("expires_in", [None, 3600])
+ async def test_valid_cached_token_is_preserved(
+ self, provider_type, expires_in, monkeypatch
+ ):
+ store = MemoryStore()
+
+ def make_provider():
+ if provider_type == "jwt":
+ return PrivateKeyJWTOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ assertion_provider=static_assertion_provider("assertion"),
+ issuer=AUTH_SERVER_URL,
+ token_storage=store,
+ )
+ return ClientCredentialsOAuthProvider(
+ SERVER_URL,
+ client_id="cid",
+ client_secret="secret",
+ issuer=AUTH_SERVER_URL,
+ token_storage=store,
+ )
+
+ await make_provider().context.storage.set_tokens(
+ OAuthToken(
+ access_token="cached",
+ token_type="Bearer",
+ expires_in=expires_in,
+ refresh_token="refresh-credential",
+ )
+ )
+ responder, captured = make_m2m_responder(token_response=self.TOKEN_RESPONSE)
+ requests: list[httpx2.Request] = []
+
+ def recording_responder(request: httpx2.Request) -> httpx2.Response:
+ requests.append(request)
+ if str(request.url) == "https://mcp.example.com/token":
+ return httpx2.Response(400, json={"error": "invalid_grant"})
+ return responder(request)
+
+ provider = make_provider()
+ async with httpx2.AsyncClient(
+ auth=provider, transport=httpx2.MockTransport(recording_responder)
+ ) as client:
+ assert (await client.post(SERVER_URL)).status_code == 200
+ assert captured["final_request"].headers["Authorization"] == "Bearer cached"
+ assert "token_request" not in captured
+
+ if expires_in is not None:
+ later = time.time() + expires_in + 1
+ monkeypatch.setattr(time, "time", lambda: later)
+ requests.clear()
+ async with httpx2.AsyncClient(
+ auth=provider, transport=httpx2.MockTransport(recording_responder)
+ ) as client:
+ assert (await client.post(SERVER_URL)).status_code == 200
+ assert str(requests[0].url) == SERVER_URL
+ assert all(
+ b"refresh-credential" not in request.content for request in requests
+ )
+ assert (
+ form_body(captured["token_request"])["grant_type"]
+ == "client_credentials"
+ )
diff --git a/tests/server/auth/test_authorization.py b/tests/server/auth/test_authorization.py
index b3f268806..132af4d95 100644
--- a/tests/server/auth/test_authorization.py
+++ b/tests/server/auth/test_authorization.py
@@ -1,14 +1,19 @@
"""Tests for authorization checks and AuthMiddleware."""
+from collections.abc import Sequence
from unittest.mock import Mock
import pytest
+from mcp import MCPError
from mcp.server.auth.middleware.auth_context import auth_context_var
from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
from fastmcp import FastMCP
from fastmcp.client import Client
-from fastmcp.exceptions import AuthorizationError, InsufficientScopeError
+from fastmcp.exceptions import AuthorizationError, InsufficientScopeError, ToolError
+from fastmcp.prompts import Prompt
+from fastmcp.resources.base import Resource
+from fastmcp.resources.template import ResourceTemplate
from fastmcp.server.auth import (
AccessToken,
AuthContext,
@@ -18,7 +23,13 @@ from fastmcp.server.auth import (
run_auth_checks,
)
from fastmcp.server.middleware import AuthMiddleware
-from fastmcp.server.transforms import ToolTransform
+from fastmcp.server.transforms import (
+ GetPromptNext,
+ GetResourceNext,
+ GetResourceTemplateNext,
+ ToolTransform,
+ Transform,
+)
from fastmcp.tools.tool_transform import ToolTransformConfig, TransformedTool
from fastmcp.utilities.authorization import scope_requirements
from fastmcp.utilities.versions import VersionSpec
@@ -1483,3 +1494,150 @@ class TestInsufficientScopeSignal:
auth_context_var.reset(tok)
assert exc_info.value.required_scopes == ["admin"]
+
+
+# =============================================================================
+# Tests that component auth sees the transformed component on direct lookups
+# =============================================================================
+
+
+class TagAdmin(Transform):
+ """Tag every resource, template, and prompt `admin`, on list and get alike."""
+
+ async def list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]:
+ return [r.model_copy(update={"tags": {"admin"}}) for r in resources]
+
+ async def get_resource(
+ self,
+ uri: str,
+ call_next: GetResourceNext,
+ *,
+ version: VersionSpec | None = None,
+ ) -> Resource | None:
+ resource = await call_next(uri, version=version)
+ return resource and resource.model_copy(update={"tags": {"admin"}})
+
+ async def list_resource_templates(
+ self, templates: Sequence[ResourceTemplate]
+ ) -> Sequence[ResourceTemplate]:
+ return [t.model_copy(update={"tags": {"admin"}}) for t in templates]
+
+ async def get_resource_template(
+ self,
+ uri: str,
+ call_next: GetResourceTemplateNext,
+ *,
+ version: VersionSpec | None = None,
+ ) -> ResourceTemplate | None:
+ template = await call_next(uri, version=version)
+ return template and template.model_copy(update={"tags": {"admin"}})
+
+ async def list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]:
+ return [p.model_copy(update={"tags": {"admin"}}) for p in prompts]
+
+ async def get_prompt(
+ self, name: str, call_next: GetPromptNext, *, version: VersionSpec | None = None
+ ) -> Prompt | None:
+ prompt = await call_next(name, version=version)
+ return prompt and prompt.model_copy(update={"tags": {"admin"}})
+
+
+class TestAuthSeesTransformedComponent:
+ """A transform that tags a component `admin` must gate direct access, not just listing."""
+
+ def make_tool_server(self) -> FastMCP:
+ mcp = FastMCP()
+
+ @mcp.tool(tags={"public"}, auth=restrict_tag("admin", scopes=["admin"]))
+ def secret() -> str:
+ return "secret"
+
+ mcp.add_transform(
+ ToolTransform({"secret": ToolTransformConfig(tags={"admin"})})
+ )
+ return mcp
+
+ async def test_tool_tagged_by_transform_is_denied_without_scope(self):
+ mcp = self.make_tool_server()
+ tok = set_token(make_token(scopes=["read"]))
+ try:
+ assert await mcp.list_tools() == []
+ assert await mcp.get_tool("secret") is None
+ async with Client(mcp) as client:
+ with pytest.raises(ToolError):
+ await client.call_tool("secret")
+ finally:
+ auth_context_var.reset(tok)
+
+ async def test_tool_tagged_by_transform_is_allowed_with_scope(self):
+ mcp = self.make_tool_server()
+ tok = set_token(make_token(scopes=["admin"]))
+ try:
+ assert [t.name for t in await mcp.list_tools()] == ["secret"]
+ async with Client(mcp) as client:
+ result = await client.call_tool("secret")
+ assert result.data == "secret"
+ finally:
+ auth_context_var.reset(tok)
+
+ async def test_resource_tagged_by_transform_is_denied_without_scope(self):
+ mcp = FastMCP()
+
+ @mcp.resource(
+ "secret://data",
+ tags={"public"},
+ auth=restrict_tag("admin", scopes=["admin"]),
+ )
+ def secret() -> str:
+ return "secret"
+
+ mcp.add_transform(TagAdmin())
+ tok = set_token(make_token(scopes=["read"]))
+ try:
+ assert await mcp.list_resources() == []
+ assert await mcp.get_resource("secret://data") is None
+ async with Client(mcp) as client:
+ with pytest.raises(MCPError):
+ await client.read_resource("secret://data")
+ finally:
+ auth_context_var.reset(tok)
+
+ async def test_template_tagged_by_transform_is_denied_without_scope(self):
+ mcp = FastMCP()
+
+ @mcp.resource(
+ "secret://{name}",
+ tags={"public"},
+ auth=restrict_tag("admin", scopes=["admin"]),
+ )
+ def secret(name: str) -> str:
+ return f"secret {name}"
+
+ mcp.add_transform(TagAdmin())
+ tok = set_token(make_token(scopes=["read"]))
+ try:
+ assert await mcp.list_resource_templates() == []
+ assert await mcp.get_resource_template("secret://{name}") is None
+ async with Client(mcp) as client:
+ with pytest.raises(MCPError):
+ await client.read_resource("secret://x")
+ finally:
+ auth_context_var.reset(tok)
+
+ async def test_prompt_tagged_by_transform_is_denied_without_scope(self):
+ mcp = FastMCP()
+
+ @mcp.prompt(tags={"public"}, auth=restrict_tag("admin", scopes=["admin"]))
+ def secret() -> str:
+ return "secret"
+
+ mcp.add_transform(TagAdmin())
+ tok = set_token(make_token(scopes=["read"]))
+ try:
+ assert await mcp.list_prompts() == []
+ assert await mcp.get_prompt("secret") is None
+ async with Client(mcp) as client:
+ with pytest.raises(MCPError):
+ await client.get_prompt("secret")
+ finally:
+ auth_context_var.reset(tok)
diff --git a/tests/server/auth/test_resource_auth_shadowing.py b/tests/server/auth/test_resource_auth_shadowing.py
new file mode 100644
index 000000000..2c34bec0f
--- /dev/null
+++ b/tests/server/auth/test_resource_auth_shadowing.py
@@ -0,0 +1,94 @@
+from collections.abc import Sequence
+
+import pytest
+from mcp import MCPError
+from mcp.server.auth.middleware.auth_context import auth_context_var
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+
+from fastmcp import Client, FastMCP
+from fastmcp.resources import Resource
+from fastmcp.server.auth import AccessToken, require_scopes
+from fastmcp.server.providers.proxy import ProxyProvider
+from fastmcp.server.transforms import GetResourceNext, Transform
+from fastmcp.utilities.versions import VersionSpec
+
+
+class ProtectConcreteResources(Transform):
+ async def list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]:
+ return [
+ resource.model_copy(update={"auth": require_scopes("admin")})
+ for resource in resources
+ ]
+
+ async def get_resource(
+ self,
+ uri: str,
+ call_next: GetResourceNext,
+ *,
+ version: VersionSpec | None = None,
+ ) -> Resource | None:
+ resource = await call_next(uri, version=version)
+ if resource is not None:
+ return resource.model_copy(update={"auth": require_scopes("admin")})
+ return None
+
+
+ "placement", ["direct", "local", "server", "provider", "mounted"]
+)
[email protected]("allowed", [False, True])
+async def test_concrete_resource_auth_shadows_template(
+ placement: str, allowed: bool
+) -> None:
+ backend = FastMCP()
+
+ @backend.resource(
+ "secret://data", auth=require_scopes("admin") if placement == "direct" else None
+ )
+ def secret() -> str:
+ return "SECRET"
+
+ @backend.resource("secret://{name}")
+ def public(name: str) -> str:
+ return f"PUBLIC {name}"
+
+ server = backend
+ uri = "secret://data"
+ other_uri = "secret://other"
+ if placement == "local":
+ backend.add_transform(ProtectConcreteResources())
+ elif placement not in {"direct", "local"}:
+ gateway = FastMCP()
+ provider = ProxyProvider(lambda: Client(backend))
+ if placement == "provider":
+ provider.add_transform(ProtectConcreteResources())
+ else:
+ gateway.add_transform(ProtectConcreteResources())
+ gateway.add_provider(provider)
+ server = gateway
+ if placement == "mounted":
+ server = FastMCP()
+ server.mount(gateway, namespace="child")
+ uri = "secret://child/data"
+ other_uri = "secret://child/other"
+
+ token = AccessToken(
+ token="test", client_id="test", scopes=["admin"] if allowed else []
+ )
+ context_token = auth_context_var.set(AuthenticatedUser(token))
+ try:
+ assert (await server.get_resource(uri) is not None) is allowed
+ async with Client(server) as client:
+ assert len(await client.list_resources()) == int(allowed)
+ if allowed:
+ result = await client.read_resource(uri)
+ assert result[0].text == "SECRET"
+ else:
+ with pytest.raises(
+ MCPError, match="Unknown resource|Resource not found"
+ ):
+ await client.read_resource(uri)
+ result = await client.read_resource(other_uri)
+ assert result[0].text == "PUBLIC other"
+ finally:
+ auth_context_var.reset(context_token)
diff --git a/tests/server/test_hashed_tool_dispatch.py b/tests/server/test_hashed_tool_dispatch.py
index dbf55f2e7..bd59907c3 100644
--- a/tests/server/test_hashed_tool_dispatch.py
+++ b/tests/server/test_hashed_tool_dispatch.py
@@ -482,7 +482,7 @@ def scoped_tool_with_auth_removed_in_mounted_server(calls: list[str]) -> FastMCP
"build, listed_name, allowed",
[
(admin_tag_removed_by_server_transform, "save", False),
- (admin_tag_added_by_server_transform, "save", True),
+ (admin_tag_added_by_server_transform, "save", False),
(admin_tag_removed_by_provider_transform, "save", True),
(admin_tag_added_by_provider_transform, "save", False),
(admin_tag_removed_in_mounted_server, "child_save", False),
diff --git a/uv.lock b/uv.lock
index 980564aaa..8abbab261 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1103,9 +1103,9 @@ requires-dist = [
{ name = "jsonref", marker = "extra == 'gemini'", specifier = ">=1.1.0" },
{ name = "jsonref", marker = "extra == 'server'", specifier = ">=1.1.0" },
{ name = "jsonschema-path", marker = "extra == 'server'", specifier = ">=0.3.4" },
- { name = "mcp", marker = "extra == 'client'", specifier = ">=2.0.0,<3.0.0" },
- { name = "mcp", marker = "extra == 'mcp'", specifier = ">=2.0.0,<3.0.0" },
- { name = "mcp", marker = "extra == 'server'", specifier = ">=2.0.0,<3.0.0" },
+ { name = "mcp", marker = "extra == 'client'", specifier = ">=2.2.0,<3.0.0" },
+ { name = "mcp", marker = "extra == 'mcp'", specifier = ">=2.2.0,<3.0.0" },
+ { name = "mcp", marker = "extra == 'server'", specifier = ">=2.2.0,<3.0.0" },
{ name = "mcp-types", specifier = ">=2.0.0,<3.0.0" },
{ name = "openai", marker = "extra == 'openai'", specifier = ">=1.102.0" },
{ name = "openapi-pydantic", marker = "extra == 'server'", specifier = ">=0.6.0" },
@@ -1764,7 +1764,7 @@ wheels = [
[[package]]
name = "mcp"
-version = "2.0.0"
+version = "2.2.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "anyio" },
@@ -1782,22 +1782,22 @@ dependencies = [
{ name = "typing-inspection" },
{ name = "uvicorn", marker = "sys_platform != 'emscripten'" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/74/33/32d4dff2c95bb5d897c3ef4c83649a08996b17b58f0a326d2495d4c81179/mcp-2.0.0.tar.gz", hash = "sha256:0f440e735c13ece8bb19bc62cf0b86f4313448432fbb77d35e14034f4e050728", size = 1662284, upload-time = "2026-07-28T13:45:32.346Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/76/31/ac54fb0fdd5b37de704486e288bba4fbbb463f24cfcfedbede407b854513/mcp-2.2.0.tar.gz", hash = "sha256:2dc37ecb1974becdcebdbf7561e7c15a07dbbf20ba21ba16c3593b3038b3afbd", size = 4084129, upload-time = "2026-09-07T16:06:23.439Z" }
wheels = [
- { url = "https://files.pythonhosted.org/packages/67/72/7d7897418912c1d12e87556630dfb7bf0eac71160e9bef8b447960804ee3/mcp-2.0.0-py3-none-any.whl", hash = "sha256:1cb4c75d2d2c7b8c1d756355e5d82a39f2822cc7f13e22a2051d7ca3592349d6", size = 349980, upload-time = "2026-07-28T13:45:28.853Z" },
+ { url = "https://files.pythonhosted.org/packages/1b/ff/8e7eade68b8a28f7da0ed1085544341b51f9c935dbf6b95c76b7edfea6a0/mcp-2.2.0-py3-none-any.whl", hash = "sha256:bde982589473a060ae145e3406e9a5333fe538c97229ba841f5a7f92be004f81", size = 365656, upload-time = "2026-09-07T16:06:19.711Z" },
]
[[package]]
name = "mcp-types"
-version = "2.0.0"
+version = "2.2.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "pydantic" },
{ name = "typing-extensions" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/bb/56/9b8e1c152f61f6c6b07c4b5896c88c7d0ae90bac6ee6306f852fcc5c1eb0/mcp_types-2.0.0.tar.gz", hash = "sha256:d7d939b9285c9961ae8866ba75ef85da34d12bafe276efbf4eb6a131786d8379", size = 66632, upload-time = "2026-07-28T13:45:33.804Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/ae/91/762d7755d971aff8a28d75f7961656148edf27875c8026e6385aaab08ae7/mcp_types-2.2.0.tar.gz", hash = "sha256:d3ed53703ddd10d9c6399f29d322bb66f3f67ab41348ac8556ba23e07fedefad", size = 65892, upload-time = "2026-09-07T16:06:25.187Z" }
wheels = [
- { url = "https://files.pythonhosted.org/packages/f5/4c/c78d78c3d52b0ac594ad7cc8ef5972adfe070e3597a8a4c6ce0cd39196ea/mcp_types-2.0.0-py3-none-any.whl", hash = "sha256:6b2de797ca2797f568b79529e1b25948e34de511bcc0bd82fef1039a6d1b8eb0", size = 69649, upload-time = "2026-07-28T13:45:30.713Z" },
+ { url = "https://files.pythonhosted.org/packages/8f/d7/6ffba5d8cd5dd9b8a19478875c50e04945314ba5074e84d749283f27f62d/mcp_types-2.2.0-py3-none-any.whl", hash = "sha256:ea476b73ee86709ab5abc9452385ed36cc05907e582355622e294595c9a04f13", size = 69106, upload-time = "2026-09-07T16:06:21.461Z" },
]
[[package]]