fix(mcp): route keyed aggregate OAuth discovery to the per-server relay and vault the claimed token

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
yassin 2026-10-20 21:39:37 +00:00
parent 5c341e7308
commit 44fe14f557
11 changed files with 1000 additions and 152 deletions

View file

@ -55,6 +55,21 @@ def _litellm_key_from_request(request: Request) -> str | None:
return None
def request_carries_litellm_credential(request: Request) -> bool:
"""Whether the request presented a litellm key or JWT at all, as opposed to resolving one that
was refused. The per-server relay keys its token response on this: an anonymous token request
(an MCP client whose OAuth fetches carry none of its MCP headers) gets a sealed claim token the
key on its next ``/mcp`` request vaults, while a presented credential keeps the upstream token
even when it could not be stored. ``Authorization: Basic`` is OAuth client authentication
(``client_secret_basic``), never a litellm credential."""
if request.headers.get("x-litellm-api-key"):
return True
authorization: Final = request.headers.get("Authorization") or request.headers.get("authorization") or ""
if authorization.strip().lower().startswith("basic "):
return False
return _litellm_key_from_request(request) is not None
async def oauth_authorization_uses_gateway_credential(request: Request) -> bool:
"""Classify credentials for browser authorize; candidates still require full authorization."""
from litellm.proxy.auth.handle_jwt import JWTHandler # noqa: PLC0415 # proxy import cycle

View file

@ -7,7 +7,7 @@ from collections.abc import AsyncIterator, Callable, Mapping
from contextlib import asynccontextmanager
from datetime import datetime, timezone
from typing import TYPE_CHECKING, Any, Final, Literal, Optional
from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
from urllib.parse import parse_qsl, quote, urlencode, urlparse, urlunparse
import httpx
from fastapi import APIRouter, Depends, Form, HTTPException, Request
@ -44,6 +44,7 @@ from litellm.proxy._experimental.mcp_server.bridge_token_flow import ( # noqa:
prepare_bridge_mint,
prepare_bridge_refresh,
reload_active_user_by_id,
request_carries_litellm_credential,
)
from litellm.proxy._experimental.mcp_server.catalog import public_catalog_operation
from litellm.proxy._experimental.mcp_server.faults import (
@ -98,6 +99,7 @@ from litellm.proxy._experimental.mcp_server.oauth_utils import (
needs_cimd_discovery,
oauth_client_registration_matches,
resolve_upstream_resource,
seal_relay_claim_token,
validate_trusted_redirect_uri,
well_known_root_suffix,
)
@ -670,7 +672,7 @@ def _validate_token_response(
)
async def _store_per_user_token_server_side(
async def store_per_user_token_server_side(
server: MCPServer,
user_id: str,
token_response: dict[str, Any],
@ -722,13 +724,13 @@ async def _store_per_user_token_server_side(
**({"cimd_client_id": cimd_client_id} if cimd_client_id is not None else {}),
)
verbose_logger.info(
"_store_per_user_token_server_side: stored token for user=%s server=%s",
"store_per_user_token_server_side: stored token for user=%s server=%s",
user_id,
server.server_id,
)
except Exception as exc:
verbose_logger.warning(
"_store_per_user_token_server_side: DB storage failed for user=%s server=%s: %s",
"store_per_user_token_server_side: DB storage failed for user=%s server=%s: %s",
user_id,
server.server_id,
exc,
@ -1540,7 +1542,7 @@ async def exchange_token_with_server(
else await authorize_oauth_credential_request(request, resolved_server.server_id) == user_id
)
if can_store:
await _store_per_user_token_server_side(
await store_per_user_token_server_side(
server=resolved_server,
user_id=user_id,
token_response=token_response,
@ -1603,6 +1605,22 @@ async def exchange_token_with_server(
if effective_scope is not None:
result["scope"] = effective_scope
anonymous_relay_token: Final = (
resolved_server.needs_user_oauth_token
and resolved_server.is_gateway_managed_oauth2
and resolved_user_id is None
and not request_carries_litellm_credential(request)
)
claim_grant: Final = TypeAdapter[dict[str, object]](dict[str, object]).validate_python(
result if "refresh_token" in result or not refresh_token else {**result, "refresh_token": refresh_token}
)
claim_token: Final = (
seal_relay_claim_token(resolved_server.server_id, claim_grant, int(time.time()), cimd_client_id=cimd_client_id)
if anonymous_relay_token
else None
)
if claim_token is not None:
return JSONResponse({**result, "access_token": claim_token}, headers=TOKEN_NO_CACHE_HEADERS)
# RFC 6749 §5.1: token responses must not be cached.
return JSONResponse(result, headers=TOKEN_NO_CACHE_HEADERS)
@ -2979,6 +2997,14 @@ def is_network_error(exc: Exception) -> bool:
return isinstance(exc, httpx.TransportError)
def _resource_scopes(mcp_server: MCPServer | None) -> tuple[str, ...]:
return tuple(
value
for value in (mcp_server.scopes or () if mcp_server else ())
if value != "offline_access" or not mcp_server or not mcp_server.is_gateway_managed_oauth2
)
@public_catalog_operation
async def _build_oauth_protected_resource_response(
request: Request,
@ -3083,11 +3109,7 @@ async def _build_oauth_protected_resource_response(
if obo_response is not None:
return obo_response
resource_scopes: Final = [
value
for value in (mcp_server.scopes or () if mcp_server else ())
if value != "offline_access" or not mcp_server or not mcp_server.is_gateway_managed_oauth2
]
resource_scopes: Final = list(_resource_scopes(mcp_server))
if mcp_server is not None and mcp_server.advertises_gateway_authorization_server:
return {
"authorization_servers": [f"{request_base_url}/mcp"],
@ -3176,13 +3198,31 @@ def _build_aggregate_protected_resource_response(request: Request) -> dict:
discovery entry point (same pattern as the per-server documents, which
advertise ``{base}/{server_name}``)."""
request_base_url: Final = get_request_base_url(request)
relay_server_name: Final = request.query_params.get("mcp_server") or ""
relay_server: Final = _keyed_relay_server(request, relay_server_name)
authorization_server: Final = (
f"{request_base_url}/{quote(relay_server_name, safe='')}" if relay_server else f"{request_base_url}/mcp"
)
return {
"authorization_servers": [f"{request_base_url}/mcp"],
"authorization_servers": [authorization_server],
"resource": f"{request_base_url}/mcp",
"scopes_supported": _aggregate_header_scopes(request),
"scopes_supported": list(_resource_scopes(relay_server)) if relay_server else _aggregate_header_scopes(request),
}
def _keyed_relay_server(request: Request, server_name: str | None) -> MCPServer | None:
"""The server the keyed aggregate 401 named in ``mcp_server``, when its sign-in is the
gateway-managed per-user flow the per-server relay completes. Anything else keeps the plain
aggregate document, so an unknown or ineligible name cannot steer discovery. A server literally
named ``mcp`` is skipped because its one-segment issuer is the aggregate sign-in."""
if not server_name or server_name == "mcp":
return None
server: Final = _resolve_mcp_server_by_name_or_id(server_name, IPAddressUtils.get_mcp_client_ip(request))
if server is None or not (server.is_gateway_managed_oauth2 and server.needs_user_oauth_token):
return None
return server
def _aggregate_header_scopes(request: Request) -> tuple[str, ...]:
"""Gateway server-scope tokens for the ``x-mcp-servers`` header a client sends with its
discovery request, so a client that skips the 401 challenge (Claude Code re-authenticating

View file

@ -118,6 +118,7 @@ from litellm.proxy._experimental.mcp_server.oauth2_token_cache import (
from litellm.proxy._experimental.mcp_server.oauth_utils import ( # noqa: F401 # legacy module exports
_redact_mcp_resource_url, # pyright: ignore[reportPrivateUsage,reportUnusedImport] # backwards-compatible package export
canonicalize_url_identity,
carries_relay_claim,
get_byok_www_authenticate,
needs_cimd_discovery,
redact_mcp_resource_url,
@ -1198,6 +1199,8 @@ def should_strip_caller_authorization(
session token whose ``api_key`` is ``None`` — and must never reach
the upstream, so it is stripped regardless of the ``api_key`` value.
"""
if carries_relay_claim(raw_headers):
return True
if _authorization_is_admission_jwt(raw_headers, user_api_key_auth):
return True
if mcp_server.auth_type == MCPAuth.oauth2_token_exchange:

View file

@ -3,6 +3,7 @@
import os
import re
import secrets
from collections.abc import Mapping
from dataclasses import dataclass
from ipaddress import ip_address
@ -11,6 +12,7 @@ from typing import TYPE_CHECKING, Final, NoReturn
from urllib.parse import ParseResult, parse_qsl, urlencode, urlparse, urlsplit, urlunparse, urlunsplit
from fastapi import HTTPException, Request
from pydantic import ConfigDict, Field, ValidationError
from starlette.types import Scope
from litellm._logging import verbose_logger
@ -23,7 +25,9 @@ from litellm.proxy._experimental.mcp_server.outbound_credentials.sso_assertion_s
GOOGLE_REFRESH_TOKEN_PARAMS,
)
from litellm.proxy.auth.ip_address_utils import IPAddressUtils
from litellm.proxy.common_utils.encrypt_decrypt_utils import decrypt_value_helper, encrypt_value_helper, get_salt_key
from litellm.proxy.middleware.per_request_root_path_middleware import get_request_root_path
from litellm.types.llms.base import LiteLLMBaseModel
if TYPE_CHECKING:
from litellm.types.mcp_server.mcp_server_manager import MCPServer
@ -322,6 +326,124 @@ def get_passthrough_www_authenticate(
return f'Bearer {error_attr}resource_metadata="{resource_metadata_url}"'
def get_keyed_aggregate_resource_metadata_url(scope: Scope, server_name: str) -> str:
"""The aggregate protected-resource metadata URL with the selected server appended, for the
401 a keyed client receives on ``/mcp``. The client's OAuth fetches carry none of its MCP
headers, so the selection rides in the URL and the document advertises that server's relay
while ``resource`` stays the ``/mcp`` URL the client connected to (RFC 9728 section 3.3)."""
base_url: Final = get_request_base_url(Request(scope))
query: Final = urlencode({"mcp_server": server_name})
return f"{base_url}/.well-known/oauth-protected-resource{well_known_root_suffix()}/mcp?{query}"
RELAY_CLAIM_TOKEN_PREFIX: Final = "llm_claim_"
RELAY_CLAIM_REDEEM_WINDOW_SECONDS: Final = 900
def is_relay_claim_bearer(authorization: str | None) -> bool:
if authorization is None:
return False
value: Final = authorization.strip()
bearer: Final = value[7:].strip() if value.lower().startswith("bearer ") else value
return bearer.startswith(RELAY_CLAIM_TOKEN_PREFIX)
def carries_relay_claim(headers: Mapping[str, str] | None) -> bool:
"""Whether the caller's ``Authorization`` is a relay claim. A claim is only ever redeemed by the
gateway, so it never travels to an upstream server (an aggregate request can fan the request-wide
``Authorization`` out to a delegate server that would otherwise receive and could replay it)."""
if headers is None:
return False
return any(key.lower() == "authorization" and is_relay_claim_bearer(value) for key, value in headers.items())
class RelayClaimToken(LiteLLMBaseModel):
"""The upstream credential the per-server relay minted for a token request that carried no
litellm key, sealed so the key on the client's next ``/mcp`` request can claim it for its
owner. Bound to the server it was issued for; a different server's challenge ignores it."""
model_config = ConfigDict(frozen=True, extra="forbid")
mcp_server_id: str = Field(min_length=1)
access_token: str = Field(min_length=1)
token_type: str = "Bearer"
refresh_token: str | None = None
expires_at: int | None = None
scope: str | None = None
cimd_client_id: str | None = None
issued_at: int
claim_id: str = Field(min_length=1)
def is_redeemable(self, now: int) -> bool:
"""A claim is redeemed right after the token exchange, so one that has outlived its upstream
access token or sat unredeemed past the window is refused rather than vaulted and refreshed."""
if self.expires_at is not None and self.expires_at <= now:
return False
return now - self.issued_at <= RELAY_CLAIM_REDEEM_WINDOW_SECONDS
def token_response(self, now: int) -> Mapping[str, object]:
expires_in: Final = max(self.expires_at - now, 0) if self.expires_at is not None else None
fields: Final = (
("access_token", self.access_token),
("token_type", self.token_type),
("refresh_token", self.refresh_token),
("expires_in", expires_in),
("scope", self.scope),
)
return MappingProxyType({key: value for key, value in fields if value is not None})
def _relay_claim_expires_at(now: int, expires_in: object) -> int | None:
if expires_in is None:
return None
try:
return now + int(float(str(expires_in)))
except ValueError:
return None
def seal_relay_claim_token(
server_id: str, token_response: Mapping[str, object], now: int, cimd_client_id: str | None = None
) -> str | None:
"""``None`` when the gateway has no signing key, in which case the per-user vault the claim
feeds cannot store anything either and the upstream token goes back as issued."""
if get_salt_key() is None:
return None
claim: Final = RelayClaimToken(
mcp_server_id=server_id,
access_token=str(token_response["access_token"]),
token_type=str(token_response.get("token_type") or "Bearer"),
refresh_token=str(token_response["refresh_token"]) if token_response.get("refresh_token") else None,
expires_at=_relay_claim_expires_at(now, token_response.get("expires_in")),
scope=str(token_response["scope"]) if token_response.get("scope") else None,
cimd_client_id=cimd_client_id,
issued_at=now,
claim_id=secrets.token_urlsafe(16),
)
return RELAY_CLAIM_TOKEN_PREFIX + encrypt_value_helper(claim.model_dump_json())
def open_relay_claim_token(authorization: str | None) -> RelayClaimToken | None:
if authorization is None:
return None
value: Final = authorization.strip()
bearer: Final = value[7:].strip() if value.lower().startswith("bearer ") else value
if not bearer.startswith(RELAY_CLAIM_TOKEN_PREFIX):
return None
decoded: Final = decrypt_value_helper(
bearer[len(RELAY_CLAIM_TOKEN_PREFIX) :],
"relay_claim_token",
exception_type="debug",
return_original_value=False,
)
if not isinstance(decoded, str):
return None
try:
return RelayClaimToken.model_validate_json(decoded)
except ValidationError:
return None
def validate_loopback_redirect_uri(redirect_uri: str) -> None:
"""Require a loopback ``redirect_uri`` (OAuth 2.1 §4.1.2.1 + RFC 8252
§7.3 native-app pattern). MCP clients are native apps that listen on

View file

@ -113,6 +113,7 @@ from litellm.proxy._experimental.mcp_server.mcp_server_manager import ( # noqa:
)
from litellm.proxy._experimental.mcp_server.oauth_utils import ( # noqa: F401 # legacy module exports
_redact_mcp_resource_url, # pyright: ignore[reportPrivateUsage,reportUnusedImport] # backwards-compatible package export
carries_relay_claim,
get_byok_www_authenticate,
redact_mcp_resource_url,
)
@ -1013,6 +1014,16 @@ def _prepare_mcp_server_headers(
explicitly-addressed operations leave it None. Per-server ``x-mcp-{alias}-authorization``
headers are unaffected — they bind one token to one server and are the multi-server shape.
"""
caller_oauth2_headers: Final = (
without_header(oauth2_headers, DEFAULT_CREDENTIAL_HEADER)
if oauth2_headers and carries_relay_claim(oauth2_headers)
else oauth2_headers
)
caller_raw_headers: Final = (
without_header(raw_headers, DEFAULT_CREDENTIAL_HEADER)
if raw_headers and carries_relay_claim(raw_headers)
else raw_headers
)
server_auth_header: dict[str, str] | str | None = None
if mcp_server_auth_headers:
from litellm.proxy._experimental.mcp_server.utils import (
@ -1033,7 +1044,7 @@ def _prepare_mcp_server_headers(
# it (RFC 9700 cross-resource replay); such scopes must bind per-server via
# x-mcp-{alias}-authorization. The decision is computed once so BOTH the forwarding branch and
# the extra_headers copy loop below honor it — otherwise a server that lists Authorization in
# extra_headers would re-copy the withheld bearer from raw_headers and replay it anyway.
# extra_headers would re-copy the withheld bearer from caller_raw_headers and replay it anyway.
withhold_forwarded_authorization: Final = is_client_forwarded_mode and caller_authorization_fans_out(
server, scope_servers
)
@ -1044,14 +1055,14 @@ def _prepare_mcp_server_headers(
extra_headers = None
else:
# Copy to avoid mutating the original dict (important for parallel fetching)
extra_headers = oauth2_headers.copy() if oauth2_headers else None
extra_headers = caller_oauth2_headers.copy() if caller_oauth2_headers else None
# Migrated authorization_code: the v2 resolver injects the stored per-user
# token, so drop the caller-forwarded Authorization (apply-if-absent would
# otherwise let it shadow the resolved token). Delegate keeps it. Centralized
# via _should_strip_caller_authorization to match _call_regular_mcp_tool.
if extra_headers and should_strip_caller_authorization(
mcp_server=server,
raw_headers=raw_headers,
raw_headers=caller_raw_headers,
user_api_key_auth=user_api_key_auth,
):
extra_headers = without_header(extra_headers, DEFAULT_CREDENTIAL_HEADER)
@ -1060,17 +1071,19 @@ def _prepare_mcp_server_headers(
extra_headers = ( # rebind-ok: pre-existing rebinding on a rename-only line
client_forwarded_authorization_headers(
mcp_server=server,
oauth2_headers=oauth2_headers,
raw_headers=raw_headers,
oauth2_headers=caller_oauth2_headers,
raw_headers=caller_raw_headers,
user_api_key_auth=user_api_key_auth,
)
)
if server.extra_headers and raw_headers:
if server.extra_headers and caller_raw_headers:
if extra_headers is None:
extra_headers = {}
normalized_raw_headers: Final = {str(k).lower(): v for k, v in raw_headers.items() if isinstance(k, str)}
normalized_caller_raw_headers: Final = {
str(k).lower(): v for k, v in caller_raw_headers.items() if isinstance(k, str)
}
# Centralized strip decision shared with
# ``MCPServerManager._call_regular_mcp_tool`` so the two
@ -1078,7 +1091,7 @@ def _prepare_mcp_server_headers(
# See ``_should_strip_caller_authorization`` for the rules.
strip_caller_authorization: Final = should_strip_caller_authorization(
mcp_server=server,
raw_headers=raw_headers,
raw_headers=caller_raw_headers,
user_api_key_auth=user_api_key_auth,
)
@ -1087,7 +1100,7 @@ def _prepare_mcp_server_headers(
continue
if header.lower() == "authorization" and (strip_caller_authorization or withhold_forwarded_authorization):
continue
header_value = normalized_raw_headers.get(header.lower())
header_value = normalized_caller_raw_headers.get(header.lower())
if header_value is None:
continue
extra_headers[header] = header_value

View file

@ -24,7 +24,9 @@ from starlette.responses import JSONResponse
from starlette.routing import Route
from starlette.types import Message, Receive, Scope, Send
from litellm._internal_context import with_service_target
from litellm._logging import verbose_logger
from litellm.caching.caching import DualCache
from litellm.constants import (
MCP_ADMISSION_BODY_PEEK_TIMEOUT_SECONDS,
MCP_GATEWAY_SESSION_ID_PREFIX_LENGTH,
@ -47,6 +49,7 @@ from litellm.proxy._experimental.mcp_server.client_allowlist import (
)
from litellm.proxy._experimental.mcp_server.discoverable_endpoints import (
get_request_base_url,
store_per_user_token_server_side,
)
from litellm.proxy._experimental.mcp_server.exceptions import (
MCPUpstreamAuthError,
@ -68,8 +71,11 @@ from litellm.proxy._experimental.mcp_server.mcp_debug import (
MCPDebug,
)
from litellm.proxy._experimental.mcp_server.oauth_utils import (
RELAY_CLAIM_REDEEM_WINDOW_SECONDS,
get_keyed_aggregate_resource_metadata_url,
get_passthrough_www_authenticate,
get_route_relative_request_path,
open_relay_claim_token,
redact_mcp_resource_url,
well_known_root_suffix,
)
@ -90,6 +96,7 @@ from litellm.proxy._experimental.mcp_server.utils import (
LITELLM_MCP_SERVER_DESCRIPTION,
LITELLM_MCP_SERVER_NAME,
LITELLM_MCP_SERVER_VERSION,
MCP_OAUTH_TOKENS_TARGET,
asgi_scope_fields,
merge_mcp_headers,
)
@ -1828,7 +1835,85 @@ if MCP_AVAILABLE:
from litellm.proxy._experimental.mcp_server.catalog import catalog_operation
@with_service_target(MCP_OAUTH_TOKENS_TARGET)
async def _reserve_relay_claim(cache: DualCache, redeemed_key: str, ttl: int) -> bool:
"""A claim is reserved with one atomic increment on the shared cache when there is one, so a
concurrent request on any worker is refused. A shared cache that cannot answer refuses the
claim rather than falling back to this worker's view, and the reservation is released again
when the save does not land."""
try:
count: Final = (
await cache.redis_cache.async_increment(redeemed_key, 1, ttl=ttl) # pyright: ignore[reportUnknownMemberType] # RedisCache is untyped
if cache.redis_cache is not None
else await cache.in_memory_cache.async_increment(redeemed_key, 1, ttl=ttl) # pyright: ignore[reportUnknownMemberType] # InMemoryCache is untyped
)
except Exception: # noqa: BLE001 # any shared-cache failure must refuse the claim, never redeem it twice
verbose_logger.warning("relay claim: the shared cache could not reserve the claim, so it is refused")
return False
return count <= 1
@with_service_target(MCP_OAUTH_TOKENS_TARGET)
async def _release_relay_claim(cache: DualCache, redeemed_key: str) -> None:
await cache.async_delete_cache(redeemed_key) # pyright: ignore[reportUnknownMemberType] # DualCache is untyped
@catalog_operation(lambda: operations.global_mcp_server_manager)
async def _claim_relay_token_for_key(
scope: Scope,
server: MCPServer,
oauth2_headers: Mapping[str, str] | None,
user_api_key_auth: UserAPIKeyAuth | None,
) -> bool:
"""A keyed client whose OAuth fetches carry no litellm key finishes the per-server relay
holding a sealed claim token instead of the upstream credential. The key on this request
is the owner the relay could not see, so vault the credential for it under the same write
policy the token endpoint applies, then let the resolver confirm it can serve the egress."""
from litellm.proxy._experimental.mcp_server.bridge_token_flow import ( # noqa: PLC0415 # proxy import cycle
can_store_oauth_credential,
)
from litellm.proxy.proxy_server import user_api_key_cache # noqa: PLC0415 # proxy import cycle
claim: Final = open_relay_claim_token(oauth2_headers.get("Authorization") if oauth2_headers else None)
now: Final = int(time.time())
if (
claim is None
or claim.mcp_server_id != server.server_id
or user_api_key_auth is None
or not claim.is_redeemable(now)
):
return False
redeemed_key: Final = f"mcp_relay_claim_redeemed:{claim.claim_id}"
if not await _reserve_relay_claim(
user_api_key_cache, redeemed_key, ttl=max(1, claim.issued_at + RELAY_CLAIM_REDEEM_WINDOW_SECONDS - now)
):
return False
try:
user_id: Final = user_api_key_auth.user_id
if not user_id or not await can_store_oauth_credential(
StarletteRequest(scope), user_api_key_auth, server.server_id
):
verbose_logger.warning(
"relay claim: the key on this request cannot store a per-user OAuth token for server=%s, "
"so the credential stays unclaimed and the client is challenged again",
server.server_id,
)
await _release_relay_claim(user_api_key_cache, redeemed_key)
return False
await store_per_user_token_server_side(
server=server,
user_id=user_id,
token_response=dict(claim.token_response(now)),
**({"cimd_client_id": claim.cimd_client_id} if claim.cimd_client_id is not None else {}),
requested_scope=claim.scope,
)
await operations.global_mcp_server_manager.invalidate_user_oauth_token_cache(user_id, server.server_id)
vaulted: Final = await operations.global_mcp_server_manager.has_user_oauth_token(server, user_api_key_auth)
except BaseException:
await _release_relay_claim(user_api_key_cache, redeemed_key)
raise
if not vaulted:
await _release_relay_claim(user_api_key_cache, redeemed_key)
return vaulted
async def _raise_preemptive_401_for_unauthenticated_servers(
scope: Scope,
mcp_servers: list[str] | None,
@ -1892,6 +1977,8 @@ if MCP_AVAILABLE:
# authorization server is the gateway itself, vaulting via the
# authorize interlude); the per-server relay advertised below
# cannot vault without a litellm key on its token request.
if await _claim_relay_token_for_key(scope, server, oauth2_headers, user_api_key_auth):
continue
if await operations.global_mcp_server_manager.has_user_oauth_token(server, user_api_key_auth):
continue
@ -1918,12 +2005,20 @@ if MCP_AVAILABLE:
_as_url = f"{as_metadata_root}/mcp/{server_name}"
else:
_as_url = f"{as_metadata_root}/{server_name}"
authorization_uri = f'Bearer authorization_uri="{_as_url}"'
authorization_uri = f'authorization_uri="{_as_url}"'
# On the aggregate route the per-server relay is also reachable through RFC 9728
# resource_metadata, the only hint standard clients follow.
named_route = _path.startswith((f"/mcp/{server_name}", f"/{server_name}/"))
resource_metadata = (
""
if named_route
else f'resource_metadata="{get_keyed_aggregate_resource_metadata_url(scope, server_name)}", '
)
raise HTTPException(
status_code=401,
detail="Unauthorized",
headers={"www-authenticate": authorization_uri},
headers={"www-authenticate": f"Bearer {resource_metadata}{authorization_uri}"},
)
if not oauth2_headers:

View file

@ -1736,6 +1736,7 @@ async def test_enforcement_rejects_preexisting_unverified_credential():
@pytest.mark.asyncio
async def test_refresh_identity_rejection_returns_reauthentication_without_persisting(monkeypatch):
from fastapi import HTTPException
from litellm.proxy._experimental.mcp_server import db as module
validator = AsyncMock(side_effect=HTTPException(status_code=403, detail="oauth_principal_mismatch"))
@ -1816,7 +1817,7 @@ async def test_saved_cimd_grant_refreshes_from_encrypted_storage_on_a_fresh_repl
from litellm.proxy import proxy_server
from litellm.proxy._experimental.mcp_server import db as db_module
from litellm.proxy._experimental.mcp_server.discoverable_endpoints import _store_per_user_token_server_side
from litellm.proxy._experimental.mcp_server.discoverable_endpoints import store_per_user_token_server_side
from litellm.proxy._experimental.mcp_server.outbound_credentials.per_user_oauth_store import (
LazyPerUserOAuthTokenStore,
)
@ -1833,7 +1834,7 @@ async def test_saved_cimd_grant_refreshes_from_encrypted_storage_on_a_fresh_repl
oauth2_flow="authorization_code", authorization_url="https://idp.example.com/authorize",
token_url="https://idp.example.com/token",
)
await _store_per_user_token_server_side(
await store_per_user_token_server_side(
server, "alice", {"access_token": "old", "refresh_token": "old-refresh", "expires_in": -10},
cimd_client_id=identity,
)

View file

@ -5895,7 +5895,9 @@ async def _bridge_register_response(
),
patch(
"litellm.proxy.utils.get_prisma_client_or_throw",
**({"return_value": MagicMock()} if database_connected else {"side_effect": HTTPException(status_code=500)}),
**(
{"return_value": MagicMock()} if database_connected else {"side_effect": HTTPException(status_code=500)}
),
),
):
response = await register_client_with_server(
@ -8117,7 +8119,7 @@ async def _exchange_persistence_attempted_for_auth_type(auth_type) -> bool:
return_value="admin-user",
),
patch(
"litellm.proxy._experimental.mcp_server.discoverable_endpoints._store_per_user_token_server_side",
"litellm.proxy._experimental.mcp_server.discoverable_endpoints.store_per_user_token_server_side",
new_callable=AsyncMock,
) as mock_store,
):
@ -9205,7 +9207,7 @@ async def test_store_per_user_token_server_side_invalidates_v2_token_cache():
until its TTL."""
from litellm.proxy._experimental.mcp_server import mcp_server_manager as manager_module
from litellm.proxy._experimental.mcp_server.discoverable_endpoints import (
_store_per_user_token_server_side,
store_per_user_token_server_side,
)
from litellm.types.mcp import MCPAuth
from litellm.types.mcp_server.mcp_server_manager import MCPServer
@ -9239,7 +9241,7 @@ async def test_store_per_user_token_server_side_invalidates_v2_token_cache():
new=invalidate_mock,
),
):
await _store_per_user_token_server_side(
await store_per_user_token_server_side(
server=server,
user_id="user-cb-1",
token_response={"access_token": "fresh-tok", "expires_in": 3600},
@ -9255,7 +9257,7 @@ async def test_store_per_user_token_server_side_skips_invalidate_when_db_write_f
previously stored token is still the truth."""
from litellm.proxy._experimental.mcp_server import mcp_server_manager as manager_module
from litellm.proxy._experimental.mcp_server.discoverable_endpoints import (
_store_per_user_token_server_side,
store_per_user_token_server_side,
)
from litellm.types.mcp import MCPAuth
from litellm.types.mcp_server.mcp_server_manager import MCPServer
@ -9289,7 +9291,7 @@ async def test_store_per_user_token_server_side_skips_invalidate_when_db_write_f
new=invalidate_mock,
),
):
await _store_per_user_token_server_side(
await store_per_user_token_server_side(
server=server,
user_id="user-cb-2",
token_response={"access_token": "fresh-tok", "expires_in": 3600},
@ -12536,7 +12538,7 @@ async def test_enforced_login_warms_verified_token_readable_without_database_loo
from litellm.caching.caching import DualCache
from litellm.proxy import proxy_server
from litellm.proxy._experimental.mcp_server import db, mcp_server_manager
from litellm.proxy._experimental.mcp_server.discoverable_endpoints import _store_per_user_token_server_side
from litellm.proxy._experimental.mcp_server.discoverable_endpoints import store_per_user_token_server_side
from litellm.proxy._experimental.mcp_server.oauth2_token_cache import mcp_per_user_token_cache
from litellm.proxy._experimental.mcp_server.oauth_identity_binding import current_binding_proof
from litellm.proxy._experimental.mcp_server.outbound_credentials.dual_cache_token_backend import (
@ -12571,7 +12573,7 @@ async def test_enforced_login_warms_verified_token_readable_without_database_loo
mcp_server_manager, "global_mcp_server_manager", SimpleNamespace(invalidate_user_oauth_token_cache=AsyncMock())
)
monkeypatch.setattr(db, "store_user_oauth_credential", AsyncMock())
await _store_per_user_token_server_side(
await store_per_user_token_server_side(
server=server,
user_id="alice",
token_response={"access_token": "alice-token", "refresh_token": "private", "expires_in": 3600},
@ -14681,7 +14683,11 @@ async def test_optional_cimd_discovery_preserves_the_callers_configured_endpoint
code_verifier=None,
)
assert response.status_code == 200
assert json.loads(response.body)["access_token"] == "upstream-access"
from litellm.proxy._experimental.mcp_server.oauth_utils import open_relay_claim_token
refreshed_claim: Final = open_relay_claim_token(f"Bearer {json.loads(response.body)['access_token']}")
assert refreshed_claim is not None and refreshed_claim.access_token == "upstream-access"
assert refreshed_claim.refresh_token == "existing-refresh"
assert parse_qs(token.calls[0].request.content.decode())["refresh_token"] == ["existing-refresh"]
else:
redirect: Final = await endpoints.authorize_with_server(
@ -14721,7 +14727,7 @@ async def test_token_route_preserves_saved_cimd_grant_after_origin_change(
table: Final = proxy_server.prisma_client.db.litellm_mcpusercredentials
table.find_unique = AsyncMock(return_value=None)
table.upsert = AsyncMock()
await endpoints._store_per_user_token_server_side(
await endpoints.store_per_user_token_server_side(
server,
"jwt-owner",
{"access_token": "expired", "refresh_token": "saved-refresh", "expires_in": -1},
@ -15271,10 +15277,16 @@ def test_root_metadata_is_the_gateways_own_and_lists_the_jwt_bearer_grant_when_i
request.base_url = "https://llm.example.com/"
request.headers = {}
with (
patch.object(discoverable_endpoints, "jwt_bearer_available", return_value=available), # test-quality-ok: deployment gate seam
patch.object(discoverable_endpoints, "token_exchange_available", return_value=True), # test-quality-ok: deployment gate seam
patch.object(
discoverable_endpoints, "jwt_bearer_available", return_value=available
), # test-quality-ok: deployment gate seam
patch.object(
discoverable_endpoints, "token_exchange_available", return_value=True
), # test-quality-ok: deployment gate seam
):
document = discoverable_endpoints._build_oauth_authorization_server_response(request=request, mcp_server_name=None)
document: Final = discoverable_endpoints._build_oauth_authorization_server_response(
request=request, mcp_server_name=None
)
assert document["issuer"] == "https://llm.example.com"
assert document["token_endpoint"] == "https://llm.example.com/token"
assert (JWT_BEARER_GRANT_TYPE in document["grant_types_supported"]) is available
@ -15302,14 +15314,215 @@ def test_root_metadata_owned_by_a_resolved_oauth2_server_never_lists_the_gateway
request.headers = {}
try:
with (
patch.object(discoverable_endpoints, "jwt_bearer_available", return_value=True), # test-quality-ok: deployment gate seam
patch.object(discoverable_endpoints, "token_exchange_available", return_value=True), # test-quality-ok: deployment gate seam
patch.object(global_mcp_server_manager, "get_mcp_server_by_name", return_value=server), # test-quality-ok: resolver seam
patch.object(
discoverable_endpoints, "jwt_bearer_available", return_value=True
), # test-quality-ok: deployment gate seam
patch.object(
discoverable_endpoints, "token_exchange_available", return_value=True
), # test-quality-ok: deployment gate seam
patch.object(
global_mcp_server_manager, "get_mcp_server_by_name", return_value=server
), # test-quality-ok: resolver seam
):
document = discoverable_endpoints._build_oauth_authorization_server_response(request=request, mcp_server_name=None)
document: Final = discoverable_endpoints._build_oauth_authorization_server_response(
request=request, mcp_server_name=None
)
finally:
global_mcp_server_manager.registry.clear()
assert document["token_endpoint"] == "https://llm.example.com/test_oauth/token"
assert JWT_BEARER_GRANT_TYPE not in document["grant_types_supported"]
assert document["grant_types_supported"] == ["authorization_code", "refresh_token"]
assert document["token_endpoint_auth_methods_supported"] == ["client_secret_post"]
def _aggregate_prm_request(query_string: bytes) -> Request:
return Request(
{
"type": "http",
"method": "GET",
"path": "/.well-known/oauth-protected-resource/mcp",
"headers": [(b"host", b"localhost:4000")],
"scheme": "http",
"server": ("localhost", 4000),
"query_string": query_string,
"root_path": "",
}
)
@pytest.mark.parametrize(
"query_string,auth_type,expected_authorization_server,expected_scopes",
(
(b"mcp_server=github_oauth", MCPAuth.oauth2, "http://localhost:4000/github_oauth", ["repo"]),
(b"mcp_server=github_oauth", MCPAuth.none, "http://localhost:4000/mcp", []),
(b"mcp_server=unknown", MCPAuth.oauth2, "http://localhost:4000/mcp", []),
(b"mcp_server=mcp", MCPAuth.oauth2, "http://localhost:4000/mcp", []),
(b"", MCPAuth.oauth2, "http://localhost:4000/mcp", []),
),
ids=("relay", "ineligible-server", "unknown-server", "server-named-mcp", "no-selector"),
)
def test_aggregate_protected_resource_relays_the_selected_gateway_managed_server(
query_string: bytes, auth_type: MCPAuth, expected_authorization_server: str, expected_scopes: list[str]
) -> None:
"""The keyed aggregate 401 appends ``mcp_server`` to its resource_metadata URL because the
client's OAuth fetches carry no headers. The document then hands that server's per-server
relay out as the authorization server while ``resource`` stays the ``/mcp`` URL the client
connected to. Anything but a gateway-managed per-user OAuth server keeps the plain document."""
from litellm.proxy._experimental.mcp_server import mcp_server_manager
from litellm.proxy._experimental.mcp_server.discoverable_endpoints import (
_build_aggregate_protected_resource_response,
)
from litellm.types.mcp_server.mcp_server_manager import MCPServer
server: Final = MCPServer(
server_id="gh-id",
name="github_oauth",
server_name="github_oauth",
url="https://github.test/mcp",
transport="http",
auth_type=auth_type,
oauth2_flow="authorization_code" if auth_type == MCPAuth.oauth2 else None,
client_id="gateway-app",
client_secret="gateway-secret",
authorization_url="https://github.test/login/oauth/authorize",
token_url="https://github.test/login/oauth/access_token",
scopes=["repo", "offline_access"],
)
manager: Final = MagicMock()
manager.get_mcp_server_by_name.side_effect = lambda name, client_ip=None: (
server if name in ("github_oauth", "mcp") else None
)
manager.get_mcp_server_by_id.return_value = None
with patch.object(mcp_server_manager, "global_mcp_server_manager", manager):
document: Final = _build_aggregate_protected_resource_response(_aggregate_prm_request(query_string))
assert document["authorization_servers"] == [expected_authorization_server]
assert document["resource"] == "http://localhost:4000/mcp"
assert list(document["scopes_supported"]) == expected_scopes
async def _exchange_on_gateway_managed_server(
monkeypatch: pytest.MonkeyPatch, request_headers: dict[str, str]
) -> dict[str, object]:
from litellm.proxy._experimental.mcp_server.discoverable_endpoints import exchange_token_with_server
from litellm.proxy._types import MCPTransport
from litellm.types.mcp_server.mcp_server_manager import MCPServer
monkeypatch.setenv("LITELLM_SALT_KEY", "sk-test-salt-lit8050-relay-claim")
server: Final = MCPServer(
server_id="gh-id",
name="github_oauth",
server_name="github_oauth",
alias="github_oauth",
transport=MCPTransport.http,
auth_type=MCPAuth.oauth2,
oauth2_flow="authorization_code",
client_id="gateway-app",
client_secret="gateway-secret",
authorization_url="https://github.test/login/oauth/authorize",
token_url="https://github.test/login/oauth/access_token",
)
mock_request: Final = MagicMock(spec=Request)
mock_request.base_url = "https://litellm.example.com/"
mock_request.headers = request_headers
upstream: Final = MagicMock()
upstream.json.return_value = {
"access_token": "ghu_upstream",
"token_type": "bearer",
"expires_in": 600,
"refresh_token": "ghr_1",
"scope": "repo",
}
upstream.raise_for_status = MagicMock()
http_client: Final = MagicMock()
http_client.post = AsyncMock(return_value=upstream)
with patch(
"litellm.proxy._experimental.mcp_server.discoverable_endpoints.get_async_httpx_client",
return_value=http_client,
):
response: Final = await exchange_token_with_server(
request=mock_request,
mcp_server=server,
grant_type="authorization_code",
code="c",
redirect_uri="http://127.0.0.1:6274/callback",
client_id="gateway-app",
client_secret=None,
code_verifier="v",
)
return json.loads(response.body)
@pytest.mark.asyncio
@pytest.mark.parametrize(
"request_headers",
({}, {"Authorization": "Basic Z2l0aHViX29hdXRoOmdhdGV3YXktc2VjcmV0"}),
ids=("no-headers", "client-secret-basic"),
)
async def test_relay_token_without_a_litellm_key_is_a_sealed_claim_for_the_server(
monkeypatch: pytest.MonkeyPatch, request_headers: dict[str, str]
) -> None:
"""The relay cannot vault for a token request that carries no litellm key, so instead of
handing the client a credential nobody owns it seals one the key on the next ``/mcp``
request can claim. The refresh token stays as issued so the client's refresh keeps working."""
from litellm.proxy._experimental.mcp_server.oauth_utils import open_relay_claim_token
with patch(
"litellm.proxy._experimental.mcp_server.discoverable_endpoints.extract_user_id_from_request",
AsyncMock(return_value=None),
):
body: Final = await _exchange_on_gateway_managed_server(monkeypatch, request_headers)
assert body["access_token"].startswith("llm_claim_")
assert body["refresh_token"] == "ghr_1"
assert body["expires_in"] == 600
claim: Final = open_relay_claim_token(f"Bearer {body['access_token']}")
assert claim is not None
assert claim.mcp_server_id == "gh-id"
assert claim.access_token == "ghu_upstream"
assert claim.refresh_token == "ghr_1"
assert claim.scope == "repo"
assert claim.token_response(now=claim.expires_at - 60)["expires_in"] == 60 # pyright: ignore[reportOptionalOperand] # expires_at set above
assert open_relay_claim_token("Bearer ghu_upstream") is None
sealed: Final = body["access_token"]
flipped: Final = "A" if sealed[-12] != "A" else "B"
assert open_relay_claim_token(f"Bearer {sealed[:-12]}{flipped}{sealed[-11:]}") is None
@pytest.mark.asyncio
async def test_relay_token_with_a_litellm_key_stays_the_upstream_token(monkeypatch: pytest.MonkeyPatch) -> None:
with (
patch(
"litellm.proxy._experimental.mcp_server.discoverable_endpoints.extract_user_id_from_request",
AsyncMock(return_value="owner"),
),
patch(
"litellm.proxy._experimental.mcp_server.discoverable_endpoints.authorize_oauth_credential_request",
AsyncMock(return_value="owner"),
),
patch(
"litellm.proxy._experimental.mcp_server.discoverable_endpoints.store_per_user_token_server_side",
AsyncMock(),
) as store,
):
body: Final = await _exchange_on_gateway_managed_server(monkeypatch, {"x-litellm-api-key": "sk-key"})
assert body["access_token"] == "ghu_upstream"
store.assert_awaited_once()
@pytest.mark.parametrize(
"expires_in,expected_expires_at",
((600, 1_600), (600.0, 1_600), ("600", 1_600), ("soon", None), (None, None)),
)
def test_relay_claim_keeps_the_upstream_expiry_whatever_number_shape_the_provider_sends(
monkeypatch: pytest.MonkeyPatch, expires_in: object, expected_expires_at: int | None
) -> None:
from litellm.proxy._experimental.mcp_server.oauth_utils import open_relay_claim_token, seal_relay_claim_token
monkeypatch.setenv("LITELLM_SALT_KEY", "sk-test-salt-lit8050-relay-claim")
token_response: Final[dict[str, object]] = {"access_token": "ghu_upstream", "expires_in": expires_in}
sealed: Final = seal_relay_claim_token(
"gh-id", token_response, now=1_000, cimd_client_id="https://c.example/c.json"
)
claim: Final = open_relay_claim_token(f"Bearer {sealed}")
assert claim is not None
assert claim.expires_at == expected_expires_at
assert claim.cimd_client_id == "https://c.example/c.json"

View file

@ -1,41 +1,32 @@
from litellm.proxy._experimental.mcp_server.upstream import resolve_upstream_auth
import importlib
import asyncio
# Add the parent directory to the path so we can import litellm
import contextlib
import functools
import importlib
import json
import logging
import os
import sys
import time
import anyio
from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
from datetime import datetime
from pathlib import Path
from types import SimpleNamespace
from typing import Any, Dict, Final, Literal, Optional, TypeVar, cast
from typing import Any, Final, Literal, TypeVar, cast
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from fastapi import HTTPException
from respx import MockRouter
from litellm.proxy._experimental.mcp_server.exceptions import (
MCPServerListError,
MCPUpstreamAuthError,
)
from litellm.proxy._experimental.mcp_server.faults.list_outcomes import ServerListFault
# Add the parent directory to the path so we can import litellm
import contextlib
import anyio
import httpx
import httpx2
import pytest
from fastapi import HTTPException
from mcp import ClientSession, ReadResourceResult, Resource
from mcp.server.context import ServerRequestContext
from mcp.types import (
CallToolRequestParams as MCPCallToolRequestParams,
)
from mcp.types import (
CallToolResult,
GetPromptResult,
ListToolsResult,
@ -46,30 +37,42 @@ from mcp.types import (
)
from mcp.types import Tool as MCPTool
from pydantic import AnyUrl, TypeAdapter
from respx import MockRouter
import litellm
import litellm.llms as litellm_llms
from litellm.caching.caching import DualCache
from litellm.caching.llm_caching_handler import LLMClientCache
from litellm.constants import MCP_METADATA_TIMEOUT, MCP_UPSTREAM_RATE_LIMIT_MAX_RETRIES
from litellm.experimental_mcp_client.client import MCPClient, PersistentMCPSession
from litellm.integrations.custom_guardrail import CustomGuardrail
from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
from litellm.proxy import proxy_server
from litellm.proxy._experimental.mcp_server import discoverable_endpoints
from litellm.proxy._experimental.mcp_server.exceptions import (
MCPServerListError,
MCPUpstreamAuthError,
)
from litellm.proxy._experimental.mcp_server.faults.list_outcomes import ServerListFault
from litellm.proxy._experimental.mcp_server.legacy_callbacks import ElicitationCallback
from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
from litellm.proxy._experimental.mcp_server.tool_outcome import TextResult
from litellm.experimental_mcp_client.client import MCPClient, PersistentMCPSession
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
ListedToolsCaller,
MCPServerManager,
global_mcp_server_manager,
_deserialize_json_dict,
_deserialize_json_list,
_flow_endpoints_missing,
_mcp_oauth_discovery_on_startup_enabled,
oauth_endpoints_unresolved,
_deserialize_json_list,
_normalize_mcp_server_cost_info,
_obo_retry_applies,
global_mcp_server_manager,
listed_tools_caller_for,
oauth_endpoints_unresolved,
resolve_openapi_tool_auth,
should_strip_caller_authorization,
listed_tools_caller_for,
)
from litellm.proxy import proxy_server
from litellm.proxy.auth import auth_checks
from litellm.proxy._experimental.mcp_server.tool_outcome import TextResult
from litellm.proxy._experimental.mcp_server.upstream import resolve_upstream_auth
from litellm.proxy._types import (
LiteLLM_MCPServerTable,
LiteLLM_ObjectPermissionTable,
@ -82,18 +85,13 @@ from litellm.proxy._types import (
MCPTransport,
UserAPIKeyAuth,
)
from litellm.types.llms.custom_http import httpxSpecialProvider
from litellm.types.mcp import MCPAuth, MCPAuthType, MCPUpstreamProtocol
from litellm.types.mcp_server.mcp_server_manager import MCPOAuthMetadata, MCPServer, PinnedMCPTool
from litellm.caching.caching import DualCache
from litellm.caching.llm_caching_handler import LLMClientCache
from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
import litellm
from litellm.integrations.custom_guardrail import CustomGuardrail
import litellm.llms as litellm_llms
from litellm.proxy.auth import auth_checks
from litellm.proxy.utils import ProxyLogging
from litellm.types.guardrails import GuardrailEventHooks
from litellm.types.integrations.slack_alerting import AlertType
from litellm.types.llms.custom_http import httpxSpecialProvider
from litellm.types.mcp import MCPAuth, MCPAuthType, MCPUpstreamProtocol
from litellm.types.mcp_server.mcp_server_manager import MCPOAuthMetadata, MCPServer, PinnedMCPTool
_TSessionResult = TypeVar("_TSessionResult")
@ -168,18 +166,19 @@ async def test_sampling_callback_keeps_creation_context_after_caller_switch():
@pytest.mark.asyncio
async def test_elicitation_callback_keeps_initiating_session():
from litellm.proxy._experimental.mcp_server import server as legacy_server
from litellm.proxy._experimental.mcp_server.mcp_server_manager import _create_elicitation_callback
from types import SimpleNamespace
from mcp.types import (
ClientCapabilities,
ElicitationCapability,
FormElicitationCapability,
ElicitRequestFormParams,
ElicitResult,
FormElicitationCapability,
)
from litellm.proxy._experimental.mcp_server import server as legacy_server
from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
from litellm.proxy._experimental.mcp_server.mcp_server_manager import _create_elicitation_callback
capabilities = ClientCapabilities(elicitation=ElicitationCapability(form=FormElicitationCapability()))
accepted = ElicitResult(action="accept")
@ -2264,7 +2263,7 @@ class TestMCPServerManager:
assert exc_info.value.fault == ServerListFault(tag="internal", status_code=412)
assert exc_info.value.server_name == "te-412-server"
def _upstream_status_error(self, status_code: int, www_authenticate: Optional[str] = None) -> httpx.HTTPStatusError:
def _upstream_status_error(self, status_code: int, www_authenticate: str | None = None) -> httpx.HTTPStatusError:
"""Build an httpx.HTTPStatusError shaped like the one the MCP SDK surfaces for an upstream
HTTP failure, so _extract_upstream_auth_failure can read status_code and WWW-Authenticate."""
request = httpx.Request("POST", "https://up.example.com/mcp")
@ -2967,11 +2966,11 @@ class TestMCPServerManager:
assert built.token_url == "https://idp.example.com/manual-token"
assert built.scopes == ["calendar.read"]
async def _capture_subject_token(self, call) -> Optional[str]:
async def _capture_subject_token(self, call) -> str | None:
"""Run a manager method (via ``call(manager)``) and return the subject_token it threaded
into ``_create_mcp_client``."""
manager = MCPServerManager()
captured: Dict[str, Any] = {}
captured: dict[str, Any] = {}
async def capture_create_mcp_client(
server, mcp_auth_header, extra_headers, stdio_env, subject_token=None, **kwargs
@ -9336,7 +9335,7 @@ class TestMCPServerTimestamps:
carry_forward_resolved_oauth_endpoints,
)
def make_server(url: str, auth_type: MCPAuth, authorization_url: Optional[str]) -> MCPServer:
def make_server(url: str, auth_type: MCPAuth, authorization_url: str | None) -> MCPServer:
return MCPServer(
server_id="s1",
name="s1",
@ -10744,7 +10743,7 @@ class TestOAuthDiscoverySSRFGuard:
}
mock_response.raise_for_status = MagicMock()
captured_kwargs: Dict[str, Any] = {}
captured_kwargs: dict[str, Any] = {}
async def fake_get(url, **kwargs):
captured_kwargs.update(kwargs)
@ -10775,7 +10774,7 @@ class TestOAuthDiscoverySSRFGuard:
}
mock_response.raise_for_status = MagicMock()
captured_kwargs: Dict[str, Any] = {}
captured_kwargs: dict[str, Any] = {}
async def fake_get(url, **kwargs):
captured_kwargs.update(kwargs)
@ -11016,8 +11015,8 @@ class TestHealthCheckInterpolatesGlobalEnvVars:
)
@staticmethod
def _capture_headers(manager: MCPServerManager) -> Dict[str, Any]:
captured: Dict[str, Any] = {}
def _capture_headers(manager: MCPServerManager) -> dict[str, Any]:
captured: dict[str, Any] = {}
mock_client = AsyncMock()
mock_client.run_with_session = AsyncMock(return_value="ok")
@ -11064,7 +11063,7 @@ class TestUserEnvVarsCacheEviction:
def _patch_cache(monkeypatch, max_size):
from litellm.proxy._experimental.mcp_server import mcp_server_manager as m
cache: Dict[Any, Any] = {}
cache: dict[Any, Any] = {}
monkeypatch.setattr(m, "_user_env_vars_cache", cache)
monkeypatch.setattr(m, "_USER_ENV_VARS_CACHE_MAX_SIZE", max_size)
return m, cache
@ -11290,7 +11289,7 @@ class TestCreateMcpClientV2Graft:
"""
def _http_server(self, **overrides: Any) -> MCPServer:
base: Dict[str, Any] = dict(
base: dict[str, Any] = dict(
server_id="http-graft",
name="graft_server",
url="https://upstream.example.com/mcp",
@ -14396,7 +14395,7 @@ class TestConfigServerIdPinning:
@pytest.mark.asyncio
async def test_two_servers_pinning_the_same_id_are_rejected(self, config_only_mcp_manager_factory):
manager = config_only_mcp_manager_factory()
config: Dict[str, Any] = {
config: dict[str, Any] = {
"docs_server": {"url": "https://a.example.com/mcp", "server_id": "shared-id"},
"wiki_server": {"url": "https://b.example.com/mcp", "server_id": "shared-id"},
}
@ -14415,7 +14414,7 @@ class TestConfigServerIdPinning:
auth_type=None,
alias=None,
)
config: Dict[str, Any] = {
config: dict[str, Any] = {
"docs_server": {"url": "https://a.example.com/mcp", "transport": MCPTransport.http},
"wiki_server": {"url": "https://b.example.com/mcp", "server_id": derived},
}
@ -15251,7 +15250,6 @@ async def test_pre_call_tool_check_honors_guardrail_attached_to_key(monkeypatch,
@pytest.mark.asyncio
async def test_pre_call_tool_check_stamps_personal_key_team_rpm_limits(monkeypatch: pytest.MonkeyPatch) -> None:
import litellm
from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import MCPRequestHandler
manager: Final = MCPServerManager()
@ -15357,7 +15355,6 @@ async def test_pre_call_tool_check_uses_inherited_team_auth_for_guardrails(monke
@pytest.mark.asyncio
async def test_pre_call_tool_check_keeps_native_name_for_team_attribution(monkeypatch: pytest.MonkeyPatch) -> None:
from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import MCPRequestHandler
server: Final = MCPServer(
server_id="math-a",
@ -15460,8 +15457,8 @@ async def test_call_tool_passes_attributed_auth_to_guardrail_hooks(monkeypatch:
from litellm.proxy import proxy_server
from litellm.proxy._experimental.mcp_server.mcp_server_manager import global_mcp_server_manager
from litellm.proxy._experimental.mcp_server.operations import _run_post_mcp_call_guardrails
from litellm.proxy.auth import auth_checks
from litellm.proxy._types import LiteLLM_ObjectPermissionTable, LiteLLM_TeamTable, LiteLLM_UserTable
from litellm.proxy.auth import auth_checks
original_auth: Final = UserAPIKeyAuth(api_key="sk-personal", user_id="alice")
team: Final = LiteLLM_TeamTable(
@ -15573,13 +15570,12 @@ async def test_call_tool_passes_attributed_auth_to_guardrail_hooks(monkeypatch:
async def test_virtual_mcp_calls_use_attributed_auth_for_logging_and_hooks(monkeypatch: pytest.MonkeyPatch) -> None:
from mcp.types import CallToolResult, Tool
from litellm.proxy import proxy_server
from litellm.proxy._experimental.mcp_server import operations, tool_search
from litellm.proxy._experimental.mcp_server.mcp_server_manager import global_mcp_server_manager
from litellm.proxy._experimental.mcp_server.tool_registry import global_mcp_tool_registry
from litellm.proxy import proxy_server
from litellm.proxy._types import LiteLLM_ObjectPermissionTable, LiteLLM_TeamTable, LiteLLM_UserTable
from litellm.proxy.auth import auth_checks
from litellm.proxy._types import LiteLLM_ObjectPermissionTable
from litellm.proxy._types import LiteLLM_TeamTable, LiteLLM_UserTable
from litellm.types.mcp_server.tool_registry import MCPTool
original_auth: Final = UserAPIKeyAuth(
@ -15718,11 +15714,11 @@ async def test_debug_resolution_matches_final_header_conflict_winner(
expected_source: str,
expected_authorization: str | None,
) -> None:
from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
from starlette.requests import Request
from pydantic import SecretStr
from starlette.requests import Request
from litellm.proxy._experimental.mcp_server.auth.litellm_auth_handler import MCPAuthenticatedUser
from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
from litellm.proxy._experimental.mcp_server.mcp_debug import MCP_AUTH_DIAGNOSTICS_SCOPE_KEY, MCPAuthDiagnostics
from litellm.proxy._experimental.mcp_server.outbound_credentials import (
ApiKeyConfig,
@ -15788,9 +15784,9 @@ async def test_debug_reports_legacy_signing_and_non_http_transport(
_mcp_request_ctx, monkeypatch, transport: Literal["http", "stdio"]
) -> None:
monkeypatch.setenv("LITELLM_ENABLE_MCP_STDIO", "true")
from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
from starlette.requests import Request
from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
from litellm.proxy._experimental.mcp_server.mcp_debug import MCP_AUTH_DIAGNOSTICS_SCOPE_KEY, MCPAuthDiagnostics
from litellm.types.mcp_server.mcp_server_manager import MCPServer
@ -16097,7 +16093,6 @@ class _DiscoveryClock:
return self.now
from pydantic import TypeAdapter
from mcp.types import JSONRPCMessage, ListPromptsResult, ListResourcesResult, ListResourceTemplatesResult
_JSONRPC_ADAPTER = TypeAdapter(JSONRPCMessage)
@ -16294,7 +16289,6 @@ def _discovery_server() -> MCPServer:
@pytest.mark.asyncio
@pytest.mark.parametrize("kind", ("prompts", "resources", "templates"))
async def test_discovery_cache_reuses_raw_results_and_expires(kind: str) -> None:
import respx
clock: Final = _DiscoveryClock()
manager: Final = MCPServerManager(discovery_clock=clock)
@ -16326,7 +16320,6 @@ async def test_discovery_cache_reuses_raw_results_and_expires(kind: str) -> None
@pytest.mark.parametrize("kind", ("prompts", "resources", "templates"))
@pytest.mark.parametrize("outcome", ("unsupported", "rejected", "failure"))
async def test_discovery_cache_empty_results_and_failures(kind: str, outcome: str) -> None:
import respx
manager: Final = MCPServerManager()
upstream: Final = _DiscoveryUpstream()
@ -16371,7 +16364,6 @@ async def test_discovery_cache_retries_failed_pagination_before_caching_complete
@pytest.mark.asyncio
async def test_discovery_cache_isolates_forwarded_credentials_and_static_auth_callers() -> None:
import respx
manager: Final = MCPServerManager()
upstream: Final = _DiscoveryUpstream()
@ -16421,7 +16413,6 @@ async def test_discovery_cache_isolates_keyless_admission_credentials(kind: str,
@pytest.mark.asyncio
async def test_discovery_cache_coalesces_and_survives_waiter_cancellation() -> None:
import respx
manager: Final = MCPServerManager()
upstream: Final = _DiscoveryUpstream()
@ -16445,7 +16436,6 @@ async def test_discovery_cache_coalesces_and_survives_waiter_cancellation() -> N
@pytest.mark.asyncio
async def test_discovery_cache_invalidation_during_fetch_does_not_repopulate_old_results() -> None:
import respx
manager: Final = MCPServerManager()
upstream: Final = _DiscoveryUpstream()
@ -16465,7 +16455,6 @@ async def test_discovery_cache_invalidation_during_fetch_does_not_repopulate_old
@pytest.mark.asyncio
async def test_discovery_cache_can_be_disabled(monkeypatch: pytest.MonkeyPatch) -> None:
import respx
monkeypatch.setenv("LITELLM_MCP_DISCOVERY_CACHE_TTL", "0")
manager: Final = MCPServerManager()
@ -16631,7 +16620,6 @@ async def test_discovery_cache_bounds_detached_fetches_without_dropping_results(
@pytest.mark.asyncio
async def test_discovery_cache_tracks_resolved_credentials_across_workers() -> None:
import respx
from litellm.proxy._experimental.mcp_server.outbound_credentials.httpx_auth import StaticHeaderAuth
from litellm.proxy._experimental.mcp_server.outbound_credentials.resolver import UpstreamCredentialProvider
from litellm.proxy._experimental.mcp_server.outbound_credentials.result import Error, Ok, Result
@ -16707,7 +16695,6 @@ async def test_discovery_cache_tracks_resolved_credentials_across_workers() -> N
@pytest.mark.asyncio
async def test_discovery_resolves_stored_oauth_for_the_requesting_user() -> None:
import respx
from litellm.proxy._experimental.mcp_server.outbound_credentials.oauth_token_store import OAuthToken
class TokenStore:
@ -17153,6 +17140,7 @@ class TestProtectedCredentialPreparation:
@pytest.mark.asyncio
async def test_static_resolution_cancellation_closes_flow(self) -> None:
from collections.abc import AsyncGenerator
from litellm.experimental_mcp_client.client import MCPClient
from litellm.proxy._experimental.mcp_server.outbound_credentials.adapter import prepare_mcp_client
@ -17418,8 +17406,8 @@ class TestProtectedCredentialPreparation:
@pytest.mark.asyncio
@pytest.mark.parametrize("selected", [False, True])
async def test_request_selected_during_guardrail_runs_concurrently_with_tool(monkeypatch, selected):
from litellm.responses.mcp.request_context import MCPRequestContext
from litellm.proxy._experimental.mcp_server import tool_registry
from litellm.responses.mcp.request_context import MCPRequestContext
tool_started = asyncio.Event()
guardrail_started = asyncio.Event()
@ -17497,6 +17485,7 @@ async def test_server_response_identifies_read_only_config(in_config, in_db, exp
@pytest.mark.parametrize("with_caller,legacy_factory", [(True, False), (False, False), (True, True)])
async def test_client_sampling_does_not_fill_explicit_context_from_another_ambient_caller(with_caller, legacy_factory):
from mcp.server.auth.middleware.auth_context import auth_context_var
from litellm.proxy._experimental.mcp_server import server as legacy_server
from litellm.proxy._experimental.mcp_server.mcp_server_manager import _create_sampling_callback
@ -17794,6 +17783,7 @@ async def test_catalog_delete_drops_derived_tool_mapping(monkeypatch):
@pytest.mark.parametrize("rediscover", [False, True])
async def test_catalog_publishes_rediscovered_routes_despite_concurrent_owner_change(monkeypatch, rediscover):
from mcp.types import Tool
from litellm.proxy import proxy_server
monkeypatch.setattr(proxy_server, "prisma_client", None)
@ -18065,6 +18055,7 @@ async def test_catalog_reload_retains_routes_discovered_for_a_late_server(change
from datetime import timedelta
from mcp.types import Tool
from litellm.proxy._experimental.mcp_server import tool_registry
row: Final = LiteLLM_MCPServerTable(
@ -18297,6 +18288,7 @@ async def test_catalog_background_lookup_after_operation_exit_observes_deletion(
@pytest.mark.asyncio
async def test_catalog_cancelled_openapi_refresh_retains_tools_and_discovery(monkeypatch):
from datetime import timedelta
from litellm.proxy._experimental.mcp_server import tool_registry
manager: Final = MCPServerManager()
@ -21125,7 +21117,9 @@ def test_openapi_extra_headers_exclude_gateway_admission_key(header_name: str) -
@pytest.mark.asyncio
async def test_legacy_upstream_elicitation_rejects_modern_downstream_without_consent() -> None:
from types import SimpleNamespace
from mcp.types import ElicitRequestFormParams, ErrorData
from litellm.proxy._experimental.mcp_server import server as legacy_server
from litellm.proxy._experimental.mcp_server.legacy_callbacks import create_elicitation_callback
from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
@ -21223,9 +21217,7 @@ class TestMCPUpstreamRateLimitRetry:
async def test_fetch_tools_with_timeout_reports_429_when_backoff_would_pass_listing_timeout(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setattr(
"litellm.proxy._experimental.mcp_server.mcp_server_manager.MCP_TOOL_LISTING_TIMEOUT", 0.5
)
monkeypatch.setattr("litellm.proxy._experimental.mcp_server.mcp_server_manager.MCP_TOOL_LISTING_TIMEOUT", 0.5)
manager: Final = MCPServerManager()
client: Final = MagicMock()
client.list_tools = AsyncMock(side_effect=_upstream_http_status_error(429, {"Retry-After": "5"}))
@ -21266,9 +21258,7 @@ class TestMCPUpstreamRateLimitRetry:
async def test_get_tools_page_retry_attempt_is_bounded_by_listing_timeout(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setattr(
"litellm.proxy._experimental.mcp_server.mcp_server_manager.MCP_TOOL_LISTING_TIMEOUT", 0.05
)
monkeypatch.setattr("litellm.proxy._experimental.mcp_server.mcp_server_manager.MCP_TOOL_LISTING_TIMEOUT", 0.05)
manager: Final = MCPServerManager()
server: Final = MCPServer(server_id="notes", name="notes", transport=MCPTransport.http)
manager.registry = {server.server_id: server}
@ -21294,3 +21284,18 @@ class TestMCPUpstreamRateLimitRetry:
assert exc_info.value.fault == ServerListFault(tag="upstream_error", status_code=429)
assert list_tools_page.await_count == 2
def test_should_strip_caller_authorization_never_forwards_a_relay_claim() -> None:
"""A relay claim is redeemed by the gateway alone, so every egress path that copies the caller's
Authorization (tool calls included) drops it, whatever the server's own forwarding mode."""
from litellm.proxy._experimental.mcp_server.mcp_server_manager import should_strip_caller_authorization
from litellm.types.mcp_server.mcp_server_manager import MCPServer
server: Final = MCPServer(server_id="plain", name="plain", url="https://up.example/mcp", transport="http")
assert should_strip_caller_authorization(
mcp_server=server, raw_headers={"authorization": "Bearer llm_claim_sealed"}, user_api_key_auth=None
)
assert not should_strip_caller_authorization(
mcp_server=server, raw_headers={"authorization": "Bearer ghu_token"}, user_api_key_auth=None
)

View file

@ -1,12 +1,13 @@
from litellm.proxy._experimental.mcp_server import operations as mcp_operations
import asyncio
import contextlib
import contextvars
import json
import os
import time
from collections.abc import Callable, Mapping
from datetime import datetime, timedelta
from types import SimpleNamespace
from typing import Callable, Final, Literal
from typing import Final, Literal, cast
from unittest.mock import AsyncMock, MagicMock, patch
import httpx
@ -33,9 +34,11 @@ from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, LATEST_HANDSHAKE_VERS
from pydantic import JsonValue, TypeAdapter
from starlette.types import Message, Receive, Scope, Send
from litellm.caching.caching import DualCache
from litellm.proxy._experimental.mcp_server import operations as mcp_operations
from litellm.proxy._experimental.mcp_server.faults.list_outcomes import AggregateToolListing
from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
from litellm.proxy._experimental.mcp_server.mcp_server_manager import ListedToolsCaller
from litellm.proxy._experimental.mcp_server.faults.list_outcomes import AggregateToolListing
from litellm.proxy._types import (
LiteLLM_MCPServerTable,
MCPTransport,
@ -365,6 +368,37 @@ def test_prepare_mcp_server_headers_case_insensitive_extra_headers():
assert extra_headers == {"Authorization": "Bearer token"}
@pytest.mark.parametrize(
"server",
(
MCPServer(server_id="plain", name="plain", transport=MCPTransport.http, extra_headers=["Authorization"]),
MCPServer(
server_id="delegate",
name="delegate",
transport=MCPTransport.http,
auth_type=MCPAuth.oauth2,
oauth2_flow="authorization_code",
oauth_delegate=True,
),
),
ids=("extra-headers-copy", "oauth-delegate"),
)
def test_prepare_mcp_server_headers_never_forwards_a_relay_claim(server: MCPServer) -> None:
"""A relay claim is redeemed by the gateway alone. In an aggregate request the request-wide
bearer fans out to every selected server, so a claim must not reach any upstream."""
from litellm.proxy._experimental.mcp_server.server import _prepare_mcp_server_headers
claim_headers: Final = {"Authorization": "Bearer llm_claim_sealed", "x-litellm-api-key": "sk-key"}
_, extra_headers = _prepare_mcp_server_headers(
server=server,
mcp_server_auth_headers=None,
mcp_auth_header=None,
oauth2_headers=dict(claim_headers),
raw_headers=dict(claim_headers),
)
assert not extra_headers or not any(key.lower() == "authorization" for key in extra_headers)
def test_prepare_mcp_server_headers_group_header_defaults_for_members_only():
try:
from litellm.proxy._experimental.mcp_server.server import (
@ -1187,6 +1221,7 @@ async def test_mcp_read_resource_success():
)
async def test_read_resource_preserves_content_metadata(_mcp_request_ctx, kind, metadata):
from mcp.types import ReadResourceRequestParams
from litellm.proxy._experimental.mcp_server import operations, server
uri: Final = "https://example.com/resource"
@ -7711,8 +7746,6 @@ def _worker_that_never_listed(server: MCPServer, upstream_tools: tuple[str, ...]
tools/list with ``upstream_tools`` and a managed dispatch that records what reaches it."""
from mcp.types import Tool as MCPTool
from litellm.proxy._experimental.mcp_server import server as mcp_module
mcp_operations.global_mcp_server_manager.registry[server.server_id] = server
dispatched: dict[str, object] = {}
@ -7745,7 +7778,6 @@ def _worker_that_never_listed(server: MCPServer, upstream_tools: tuple[str, ...]
async def test_execute_mcp_tool_lists_never_listed_passthrough_server_with_caller_token_first():
"""A prefixed tools/call on a worker that has not served tools/list must list that server once
with the caller's own credentials and then dispatch, instead of answering 404."""
from litellm.proxy._experimental.mcp_server import server as mcp_module
server = _never_listed_passthrough_server()
with _worker_that_never_listed(server, upstream_tools=("add",)) as worker:
@ -7766,7 +7798,6 @@ async def test_execute_mcp_tool_lists_never_listed_passthrough_server_with_calle
@pytest.mark.asyncio
async def test_execute_mcp_tool_rest_server_id_lists_never_listed_server_first():
from litellm.proxy._experimental.mcp_server import server as mcp_module
server = _never_listed_passthrough_server()
with _worker_that_never_listed(server, upstream_tools=("add",)) as worker:
@ -7786,7 +7817,6 @@ async def test_execute_mcp_tool_rest_server_id_lists_never_listed_server_first()
@pytest.mark.asyncio
async def test_execute_mcp_tool_unknown_tool_on_never_listed_server_lists_once_then_404s():
from litellm.proxy._experimental.mcp_server import server as mcp_module
server = _never_listed_passthrough_server()
with (
@ -7810,8 +7840,6 @@ async def test_execute_mcp_tool_unknown_tool_on_never_listed_server_lists_once_t
async def test_execute_mcp_tool_does_not_relist_a_server_this_worker_already_listed():
from mcp.types import Tool as MCPTool
from litellm.proxy._experimental.mcp_server import server as mcp_module
server = _never_listed_passthrough_server()
with _worker_that_never_listed(server, upstream_tools=("add",)) as worker:
mcp_operations.global_mcp_server_manager._create_prefixed_tools([MCPTool(name="add", inputSchema={})], server)
@ -7833,8 +7861,6 @@ async def test_execute_mcp_tool_lists_a_tool_this_worker_has_not_yet_seen_on_a_l
for a different tool it has not cached, so callers with wider upstream catalogs are not 404ed."""
from mcp.types import Tool as MCPTool
from litellm.proxy._experimental.mcp_server import server as mcp_module
server = _never_listed_passthrough_server()
with _worker_that_never_listed(server, upstream_tools=("add", "multiply")) as worker:
mcp_operations.global_mcp_server_manager._create_prefixed_tools([MCPTool(name="add", inputSchema={})], server)
@ -7853,7 +7879,6 @@ async def test_execute_mcp_tool_lists_a_tool_this_worker_has_not_yet_seen_on_a_l
@pytest.mark.asyncio
async def test_execute_mcp_tool_never_lists_a_server_the_caller_cannot_access():
from litellm.proxy._experimental.mcp_server import server as mcp_module
server = _never_listed_passthrough_server()
other_server = MCPServer(server_id="other-1", name="other", transport=MCPTransport.http)
@ -8226,7 +8251,6 @@ async def test_execute_mcp_tool_sets_model_in_model_call_details():
import uuid
from datetime import timezone
from litellm.proxy._experimental.mcp_server import server as mcp_module
from litellm.proxy._types import LitellmUserRoles
from litellm.utils import Rules, function_setup
@ -10258,9 +10282,7 @@ async def test_handle_list_tools_all_faults_on_continuation_stays_degraded(
outcomes={"a": ServerListFault(tag="upstream_error", status_code=429)},
)
result: Final = await _list_tools_with_listing(
_mcp_request_ctx, listing, PaginatedRequestParams(cursor="cursor-1")
)
result: Final = await _list_tools_with_listing(_mcp_request_ctx, listing, PaginatedRequestParams(cursor="cursor-1"))
assert isinstance(result, ListToolsResult)
assert result.tools == []
@ -10361,7 +10383,6 @@ class TestPreemptive401ModeAware:
@pytest.mark.asyncio
async def test_deferred_discovery_runs_before_delegate_challenge(self):
from litellm.proxy._experimental.mcp_server import server as server_module
manager = mcp_operations.global_mcp_server_manager
server = _make_oauth2_server(
@ -10393,7 +10414,6 @@ class TestPreemptive401ModeAware:
@pytest.mark.asyncio
async def test_stamped_m2m_challenge_skips_deferred_discovery(self):
from litellm.proxy._experimental.mcp_server import server as server_module
manager = mcp_operations.global_mcp_server_manager
server = _make_oauth2_server("stamped_m2m", oauth2_flow="client_credentials")
@ -10805,8 +10825,8 @@ async def test_post_mcp_call_guardrails_propagate_a_block():
async def test_post_mcp_call_guardrails_preserve_and_deduplicate_mapping_entries(
monkeypatch: pytest.MonkeyPatch,
) -> None:
from litellm.proxy._experimental.mcp_server.server import _run_post_mcp_call_guardrails
from litellm.proxy import proxy_server
from litellm.proxy._experimental.mcp_server.server import _run_post_mcp_call_guardrails
monkeypatch.setattr("litellm.proxy.utils.premium_user_check", MagicMock())
monkeypatch.setattr(proxy_server, "premium_user", True, raising=False)
@ -11282,8 +11302,8 @@ async def test_native_listing_preserves_empty_result_on_auth_failure(_mcp_reques
@pytest.mark.asyncio
@pytest.mark.parametrize("failure_hook_raises", [False, True])
async def test_tool_listing_preserves_permission_denial_when_failure_logging_fails(failure_hook_raises):
from litellm.proxy._experimental.mcp_server import operations
from litellm.proxy import proxy_server
from litellm.proxy._experimental.mcp_server import operations
auth = UserAPIKeyAuth(user_id="denied-caller")
denial = HTTPException(status_code=403, detail="scope denied")
@ -11319,8 +11339,9 @@ async def test_legacy_sse_mount_emits_message_endpoint(
) -> None:
from starlette.applications import Starlette
from starlette.routing import Mount
from litellm.proxy._experimental.mcp_server.faults.list_outcomes import AggregateToolListing
from litellm.proxy._experimental.mcp_server import server as mcp_server
from litellm.proxy._experimental.mcp_server.faults.list_outcomes import AggregateToolListing
app: Final = Starlette(routes=[Mount("/mcp", app=mcp_server.app)])
incoming: Final[asyncio.Queue[Message]] = asyncio.Queue()
@ -11478,6 +11499,7 @@ def test_protocol_header_respects_configured_advertisement(revision, rejected):
@pytest.mark.asyncio
async def test_discovery_adapter_preserves_authenticated_context(_mcp_request_ctx):
from mcp.types import DiscoverResult, RequestParams, ServerCapabilities
from litellm.proxy._experimental.mcp_server import server
expected = DiscoverResult(supported_versions=["2025-11-25"], capabilities=ServerCapabilities())
@ -11520,12 +11542,13 @@ async def test_modern_oauth_challenge_follows_continuation_authorization(
route_name: str,
monkeypatch: pytest.MonkeyPatch,
) -> None:
import time
from mcp.types import InputRequiredResult
from pydantic import TypeAdapter
from litellm.proxy._experimental.mcp_server import server
from litellm.proxy._experimental.mcp_server.contracts import OperationContext
from litellm.proxy._experimental.mcp_server.interactions import InteractionOperation, bind_target, seal_continuation
from mcp.types import InputRequiredResult
monkeypatch.setenv("LITELLM_SALT_KEY", "challenge-test-salt")
monkeypatch.setattr("litellm.proxy.proxy_server.general_settings", {"mcp_advertised_versions": ["2026-07-28"]})
@ -11786,9 +11809,10 @@ async def test_modern_preflight_leaves_invalid_envelopes_to_sdk_without_upstream
@pytest.mark.parametrize("forwarded_token", (False, True))
async def test_modern_passthrough_probe_uses_scrubbed_server_credential(binding: str, forwarded_token: bool):
import respx
from litellm.proxy._types import LiteLLM_ObjectPermissionTable
from litellm.proxy._experimental.mcp_server import server
from litellm.proxy._experimental.mcp_server.contracts import OperationContext
from litellm.proxy._types import LiteLLM_ObjectPermissionTable
target: Final = MCPServer(
server_id="probe-id",
@ -11859,8 +11883,9 @@ async def test_modern_passthrough_probe_uses_scrubbed_server_credential(binding:
@pytest.mark.parametrize("header_shape", ("mapping", "non_authorization"))
async def test_passthrough_probes_bind_each_token_to_its_authorized_server(allowed: bool, header_shape: str):
import respx
from litellm.proxy._types import LiteLLM_ObjectPermissionTable
from litellm.proxy._experimental.mcp_server import server
from litellm.proxy._types import LiteLLM_ObjectPermissionTable
targets: Final = [
MCPServer(
@ -12047,7 +12072,6 @@ async def test_stateful_cancellation_does_not_wait_for_call_or_change_its_auth(p
@pytest.mark.parametrize("selected", [False, True])
async def test_progress_text_obeys_request_output_guardrails(monkeypatch, action, message, selected):
import litellm
from litellm.caching.caching import DualCache
from litellm.proxy import proxy_server
from litellm.proxy._experimental.mcp_server.operations import _guarded_progress_callback
@ -12097,13 +12121,12 @@ async def test_execute_mcp_tool_derives_team_guardrail_auth_for_personal_keys(
monkeypatch: pytest.MonkeyPatch,
) -> None:
import litellm
from litellm.caching.caching import DualCache
from litellm.proxy import proxy_server
from litellm.proxy._experimental.mcp_server.mcp_server_manager import global_mcp_server_manager
from litellm.proxy._experimental.mcp_server.utils import get_server_prefix
from litellm.proxy.auth import auth_checks
from litellm.proxy._types import LiteLLM_ObjectPermissionTable, LiteLLM_TeamTable, LiteLLM_UserTable
from litellm.proxy.auth import auth_checks
from litellm.proxy.utils import ProxyLogging
user_api_key_auth: Final = UserAPIKeyAuth(api_key="sk-personal", user_id="owner")
@ -12180,3 +12203,315 @@ async def test_execute_mcp_tool_derives_team_guardrail_auth_for_personal_keys(
guardrail_auth: Final = proxy_logging_obj.pre_call_hook.await_args.kwargs["user_api_key_dict"]
assert guardrail_auth.team_id == "team-a"
assert guardrail_auth.team_metadata == {"guardrails": ["team-guardrail"]}
def _keyed_scope(path: str) -> Scope:
return {
"type": "http",
"method": "POST",
"path": path,
"raw_path": path.encode(),
"query_string": b"",
"root_path": "",
"scheme": "http",
"server": ("localhost", 4000),
"client": ("127.0.0.1", 1234),
"headers": [(b"host", b"localhost:4000")],
}
class TestKeyedAggregateRelayClaim:
"""A virtual-key client on the aggregate ``/mcp`` route whose OAuth fetches carry none of its
MCP headers (Cursor) must still reach the upstream identity provider through RFC 9728
discovery and end up with the upstream credential vaulted under the key's owner."""
SALT: Final = "sk-test-salt-lit8050-relay-claim"
NOW: Final = 1_800_000_000
UPSTREAM_TOKEN: Final = {
"access_token": "ghu_upstream",
"refresh_token": "ghr_1",
"expires_in": 600,
"scope": "repo",
}
async def _run(
self,
server: MCPServer,
path: str,
oauth2_headers: Mapping[str, str] | None,
auth: UserAPIKeyAuth,
has_token: list[bool],
cache: DualCache | None = None,
store: AsyncMock | None = None,
) -> AsyncMock:
from litellm.proxy._experimental.mcp_server import server as server_module
manager: Final = mcp_operations.global_mcp_server_manager
store = store if store is not None else AsyncMock() # rebind-ok: default for the injected store double
with (
patch("time.time", return_value=self.NOW),
patch("litellm.proxy.proxy_server.user_api_key_cache", cache if cache is not None else DualCache()),
patch.object(manager, "get_mcp_server_by_name", return_value=server),
patch.object(manager, "has_user_oauth_token", AsyncMock(side_effect=has_token)),
patch.object(manager, "invalidate_user_oauth_token_cache", AsyncMock()),
patch.object(server_module, "store_per_user_token_server_side", store),
):
await server_module._raise_preemptive_401_for_unauthenticated_servers(
scope=_keyed_scope(path),
mcp_servers=[server.alias],
oauth2_headers=oauth2_headers,
mcp_server_auth_headers=None,
user_api_key_auth=auth,
client_ip=None,
)
return store
def _claim(self, server_id: str, cimd_client_id: str | None = None, issued_at: int | None = None) -> dict[str, str]:
from litellm.proxy._experimental.mcp_server.oauth_utils import seal_relay_claim_token
now: Final = issued_at if issued_at is not None else self.NOW
sealed: Final = seal_relay_claim_token(server_id, self.UPSTREAM_TOKEN, now=now, cimd_client_id=cimd_client_id)
return {"Authorization": f"Bearer {sealed}"}
@pytest.mark.asyncio
async def test_aggregate_challenge_names_the_relay_through_resource_metadata(self):
server: Final = _make_oauth2_server("github_oauth", oauth2_flow="authorization_code")
with pytest.raises(HTTPException) as challenged:
await self._run(server, "/mcp", None, UserAPIKeyAuth(api_key="sk-key", user_id="owner"), [False])
assert challenged.value.status_code == 401
assert challenged.value.headers["www-authenticate"] == (
'Bearer resource_metadata="http://localhost:4000/.well-known/oauth-protected-resource/mcp'
'?mcp_server=github_oauth", '
'authorization_uri="http://localhost:4000/.well-known/oauth-authorization-server/github_oauth"'
)
@pytest.mark.asyncio
async def test_named_route_challenge_is_unchanged(self):
server: Final = _make_oauth2_server("github_oauth", oauth2_flow="authorization_code")
with pytest.raises(HTTPException) as challenged:
await self._run(
server, "/mcp/github_oauth", None, UserAPIKeyAuth(api_key="sk-key", user_id="owner"), [False]
)
assert challenged.value.headers["www-authenticate"] == (
'Bearer authorization_uri="http://localhost:4000/.well-known/oauth-authorization-server/mcp/github_oauth"'
)
@pytest.mark.asyncio
async def test_claim_token_is_vaulted_for_the_key_owner(self, monkeypatch: pytest.MonkeyPatch):
monkeypatch.setenv("LITELLM_SALT_KEY", self.SALT)
server: Final = _make_oauth2_server("github_oauth", oauth2_flow="authorization_code")
with patch(
"litellm.proxy._experimental.mcp_server.bridge_token_flow.can_store_oauth_credential",
AsyncMock(return_value=True),
):
store: Final = await self._run(
server,
"/mcp",
self._claim(server.server_id, cimd_client_id="https://cursor.example/client.json"),
UserAPIKeyAuth(api_key="sk-key", user_id="owner"),
[True],
)
store.assert_awaited_once()
stored: Final = store.await_args.kwargs
assert stored["server"] is server
assert stored["user_id"] == "owner"
assert stored["token_response"]["access_token"] == "ghu_upstream"
assert stored["token_response"]["refresh_token"] == "ghr_1"
assert stored["token_response"]["expires_in"] == 600
assert stored["requested_scope"] == "repo"
assert stored["cimd_client_id"] == "https://cursor.example/client.json"
@pytest.mark.asyncio
async def test_claim_token_lands_in_the_credential_store_as_the_key_owner(self, monkeypatch: pytest.MonkeyPatch):
"""The claim path runs the real server-side store, only the DB and cache edges are doubled,
so the row written for the key owner carries the upstream grant the client consented to."""
from litellm.proxy._experimental.mcp_server import mcp_server_manager as manager_module
from litellm.proxy._experimental.mcp_server import server as server_module
monkeypatch.setenv("LITELLM_SALT_KEY", self.SALT)
server: Final = _make_oauth2_server("github_oauth", oauth2_flow="authorization_code")
manager: Final = manager_module.global_mcp_server_manager
db_store: Final = AsyncMock(return_value=None)
with (
patch.object(manager, "get_mcp_server_by_name", return_value=server),
patch.object(manager, "has_user_oauth_token", AsyncMock(return_value=True)),
patch.object(manager, "invalidate_user_oauth_token_cache", AsyncMock()),
patch("litellm.proxy.utils.get_prisma_client_or_throw", return_value=MagicMock()),
patch("litellm.proxy._experimental.mcp_server.db.store_user_oauth_credential", new=db_store),
patch(
"litellm.proxy._experimental.mcp_server.oauth2_token_cache.mcp_per_user_token_cache.set",
new=AsyncMock(return_value=None),
),
patch(
"litellm.proxy._experimental.mcp_server.bridge_token_flow.can_store_oauth_credential",
AsyncMock(return_value=True),
),
):
await server_module._raise_preemptive_401_for_unauthenticated_servers(
scope=_keyed_scope("/mcp"),
mcp_servers=[server.alias],
oauth2_headers=self._claim(server.server_id, cimd_client_id="https://cursor.example/client.json"),
mcp_server_auth_headers=None,
user_api_key_auth=UserAPIKeyAuth(api_key="sk-key", user_id="owner"),
client_ip=None,
)
db_store.assert_awaited_once()
row: Final = db_store.await_args.kwargs
assert row["user_id"] == "owner"
assert row["server_id"] == server.server_id
assert row["access_token"] == "ghu_upstream"
assert row["refresh_token"] == "ghr_1"
assert row["cimd_client_id"] == "https://cursor.example/client.json"
@pytest.mark.asyncio
@pytest.mark.parametrize(
"claim_server_id,auth,can_store",
(
("some-other-server", UserAPIKeyAuth(api_key="sk-key", user_id="owner"), True),
("id-github_oauth", UserAPIKeyAuth(api_key="sk-key", user_id="outsider"), False),
("id-github_oauth", UserAPIKeyAuth(api_key="sk-team-key", user_id=None), True),
),
ids=("other-server", "write-policy-refuses", "key-without-owner"),
)
async def test_claim_token_the_key_may_not_vault_is_challenged_again(
self, monkeypatch: pytest.MonkeyPatch, claim_server_id: str, auth: UserAPIKeyAuth, can_store: bool
):
monkeypatch.setenv("LITELLM_SALT_KEY", self.SALT)
server: Final = _make_oauth2_server("github_oauth", oauth2_flow="authorization_code")
with (
patch(
"litellm.proxy._experimental.mcp_server.bridge_token_flow.can_store_oauth_credential",
AsyncMock(return_value=can_store),
),
pytest.raises(HTTPException) as challenged,
):
await self._run(server, "/mcp", self._claim(claim_server_id), auth, [False])
assert challenged.value.status_code == 401
assert "resource_metadata=" in challenged.value.headers["www-authenticate"]
@pytest.mark.asyncio
@pytest.mark.parametrize(
"upstream_token,issued_at_offset",
(
({"access_token": "ghu_upstream", "expires_in": 600}, -1_200),
({"access_token": "ghu_upstream"}, -1_000),
),
ids=("upstream-token-expired", "no-expiry-past-redeem-window"),
)
async def test_stale_claim_is_refused_not_vaulted(
self, monkeypatch: pytest.MonkeyPatch, upstream_token: dict[str, object], issued_at_offset: int
):
from litellm.proxy._experimental.mcp_server.oauth_utils import seal_relay_claim_token
monkeypatch.setenv("LITELLM_SALT_KEY", self.SALT)
server: Final = _make_oauth2_server("github_oauth", oauth2_flow="authorization_code")
sealed: Final = seal_relay_claim_token(server.server_id, upstream_token, now=self.NOW + issued_at_offset)
can_store: Final = AsyncMock(return_value=True)
with patch("litellm.proxy._experimental.mcp_server.bridge_token_flow.can_store_oauth_credential", can_store):
with pytest.raises(HTTPException) as challenged:
await self._run(
server,
"/mcp",
{"Authorization": f"Bearer {sealed}"},
UserAPIKeyAuth(api_key="sk-key", user_id="owner"),
[False],
)
can_store.assert_not_awaited()
assert challenged.value.status_code == 401
@pytest.mark.asyncio
async def test_claim_is_redeemed_once_so_a_re_presented_claim_cannot_undo_a_refresh(
self, monkeypatch: pytest.MonkeyPatch
):
"""MCP clients attach the bearer they hold to every request. The claim they hold is redeemed
on the first one and remembered, so later requests cannot rewrite a grant the gateway has
since refreshed."""
monkeypatch.setenv("LITELLM_SALT_KEY", self.SALT)
server: Final = _make_oauth2_server("github_oauth", oauth2_flow="authorization_code")
claim: Final = self._claim(server.server_id)
cache: Final = DualCache()
auth: Final = UserAPIKeyAuth(api_key="sk-key", user_id="owner")
with patch(
"litellm.proxy._experimental.mcp_server.bridge_token_flow.can_store_oauth_credential",
AsyncMock(return_value=True),
):
first: Final = await self._run(server, "/mcp", claim, auth, [True], cache)
with pytest.raises(HTTPException) as challenged:
await self._run(server, "/mcp", claim, auth, [False], cache)
first.assert_awaited_once()
assert challenged.value.status_code == 401
assert "mcp_server=github_oauth" in challenged.value.headers["www-authenticate"]
@pytest.mark.asyncio
async def test_a_claim_whose_save_did_not_land_can_be_redeemed_again(self, monkeypatch: pytest.MonkeyPatch):
"""The store swallows a failed database write. The claim is then released instead of spent,
so the client's retry vaults the grant once the database is back."""
monkeypatch.setenv("LITELLM_SALT_KEY", self.SALT)
server: Final = _make_oauth2_server("github_oauth", oauth2_flow="authorization_code")
claim: Final = self._claim(server.server_id)
cache: Final = DualCache()
auth: Final = UserAPIKeyAuth(api_key="sk-key", user_id="owner")
with patch(
"litellm.proxy._experimental.mcp_server.bridge_token_flow.can_store_oauth_credential",
AsyncMock(return_value=True),
):
with pytest.raises(HTTPException) as challenged:
await self._run(server, "/mcp", claim, auth, [False, False], cache)
retry: Final = await self._run(server, "/mcp", claim, auth, [True], cache)
assert challenged.value.status_code == 401
retry.assert_awaited_once()
assert retry.await_args.kwargs["token_response"]["access_token"] == "ghu_upstream"
@pytest.mark.asyncio
async def test_a_claim_whose_save_blew_up_is_released_for_the_retry(self, monkeypatch: pytest.MonkeyPatch):
monkeypatch.setenv("LITELLM_SALT_KEY", self.SALT)
server: Final = _make_oauth2_server("github_oauth", oauth2_flow="authorization_code")
claim: Final = self._claim(server.server_id)
cache: Final = DualCache()
auth: Final = UserAPIKeyAuth(api_key="sk-key", user_id="owner")
with patch(
"litellm.proxy._experimental.mcp_server.bridge_token_flow.can_store_oauth_credential",
AsyncMock(return_value=True),
):
with pytest.raises(RuntimeError):
await self._run(server, "/mcp", claim, auth, [], cache, store=AsyncMock(side_effect=RuntimeError("db")))
retry: Final = await self._run(server, "/mcp", claim, auth, [True], cache)
retry.assert_awaited_once()
@pytest.mark.asyncio
async def test_concurrent_requests_reserve_a_claim_exactly_once(self):
from litellm.proxy._experimental.mcp_server import server as server_module
cache: Final = DualCache()
outcomes: Final = await asyncio.gather(
*(server_module._reserve_relay_claim(cache, "mcp_relay_claim_redeemed:one", ttl=60) for _ in range(8))
)
assert outcomes.count(True) == 1
await server_module._release_relay_claim(cache, "mcp_relay_claim_redeemed:one")
assert await server_module._reserve_relay_claim(cache, "mcp_relay_claim_redeemed:one", ttl=60)
@pytest.mark.asyncio
async def test_a_shared_cache_that_cannot_answer_refuses_the_claim(self):
"""Several workers share one Redis. When it is down, this worker's own view is not enough to
know the claim is unspent, so the claim is refused instead of redeemed twice."""
from litellm.caching.redis_cache import RedisCache
from litellm.proxy._experimental.mcp_server import server as server_module
down: Final = cast(
RedisCache, SimpleNamespace(async_increment=AsyncMock(side_effect=ConnectionError("redis down")))
)
cache: Final = DualCache(redis_cache=down)
assert not await server_module._reserve_relay_claim(cache, "mcp_relay_claim_redeemed:two", ttl=60)
@pytest.mark.asyncio
async def test_garbage_bearer_is_not_a_claim(self):
server: Final = _make_oauth2_server("github_oauth", oauth2_flow="authorization_code")
with pytest.raises(HTTPException) as challenged:
await self._run(
server,
"/mcp",
{"Authorization": "Bearer llm_claim_not-a-sealed-token"},
UserAPIKeyAuth(api_key="sk-key", user_id="owner"),
[False],
)
assert challenged.value.status_code == 401

View file

@ -666,7 +666,15 @@ async def test_per_user_oauth_missing_stored_token_returns_preemptive_401():
assert mock_handle_request.await_count == 0
assert exc_info.value.status_code == 401
assert "www-authenticate" in exc_info.value.headers
assert "Bearer authorization_uri=" in exc_info.value.headers["www-authenticate"]
challenge = exc_info.value.headers["www-authenticate"]
assert challenge.startswith(
'Bearer resource_metadata="http://localhost:8000/.well-known/oauth-protected-resource/mcp'
'?mcp_server=repro_oauth_server"'
)
assert (
'authorization_uri="http://localhost:8000/.well-known/oauth-authorization-server/repro_oauth_server"'
in challenge
)
@pytest.mark.asyncio
@ -1827,9 +1835,7 @@ async def test_streamable_http_skips_preflight_for_disabled_methods( # test-qua
"tp_server",
extra_headers=request_headers,
)
body: Final[bytes] = json.dumps(
{"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
).encode()
body: Final[bytes] = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}).encode()
receive: Final = AsyncMock(return_value={"type": "http.request", "body": body, "more_body": False})
send: Final = AsyncMock()
user_auth: Final = UserAPIKeyAuth()