fix(mcp): fail closed on missing upstream credentials

litellm/experimental_mcp_client/client.py

@@ -346,13 +346,17 @@ def __init__(
             self.update_auth_value(auth_value)
 
     async def discovery_auth_fingerprint(self) -> str:
+        return self._hash_discovery_auth(await self.prepare_request_auth())
+
+    async def prepare_request_auth(self) -> httpx.Request:
+        """Preview the authenticated request without sending it, closing the auth flow afterwards."""
         request: Final = httpx.Request("POST", self.server_url or "http://localhost/", headers=self._get_auth_headers())
         if self._resolved_auth is None:
-            return self._hash_discovery_auth(request)
+            return request
         flow: Final = self._resolved_auth.async_auth_flow(request)
         try:
             authenticated: Final = await flow.__anext__()
-            return self._hash_discovery_auth(authenticated)
+            return authenticated
         finally:
             await flow.aclose()
 

litellm/proxy/_experimental/mcp_server/mcp_server_manager.py

@@ -102,6 +102,7 @@
     UpstreamCredentialProvider,
 )
 from litellm.proxy._experimental.mcp_server.outbound_credentials.adapter import (
+    prepare_mcp_client,
     raise_public,
     raise_token_exchange_challenge,
     raise_user_oauth_challenge,
@@ -2804,6 +2805,8 @@ async def _register_openapi_tools(self, spec_path: str, server: MCPServer, base_
                         headers=headers,
                         server_label=server.name or server.server_name or server.alias or server.server_id,
                         relays_upstream_auth=server.is_client_forwarded_token,
+                        auth_type=server.auth_type,
+                        upstream_token_header=server.upstream_token_header,
                     )
                     tool_func.__name__ = prefixed_tool_name
                     tool_func.__doc__ = description
@@ -4259,15 +4262,20 @@ async def _create_mcp_client(
                     user_api_key_auth=user_api_key_auth,
                     extra_headers=extra_headers,
                 )
-                return MCPClient(
-                    server_url=server_url,
-                    transport_type=transport,
-                    auth_type=resolved_server.auth_type,
-                    timeout=(resolved_server.timeout if resolved_server.timeout is not None else MCP_CLIENT_TIMEOUT),
-                    extra_headers=extra_headers,
-                    resolved_auth=resolved_auth,
-                    sampling_callback=sampling_cb,
-                    elicitation_callback=elicitation_cb,
+                return await prepare_mcp_client(
+                    resolved_server,
+                    MCPClient(
+                        server_url=server_url,
+                        transport_type=transport,
+                        auth_type=resolved_server.auth_type,
+                        timeout=(
+                            resolved_server.timeout if resolved_server.timeout is not None else MCP_CLIENT_TIMEOUT
+                        ),
+                        extra_headers=extra_headers,
+                        resolved_auth=resolved_auth,
+                        sampling_callback=sampling_cb,
+                        elicitation_callback=elicitation_cb,
+                    ),
                 )
 
             # Create SigV4 auth if configured
@@ -4297,17 +4305,20 @@ async def _create_mcp_client(
                 else AuthResolution.no_auth
             )
             record_auth_resolution(server.server_id, legacy_source)
-            return MCPClient(
-                server_url=server_url,
-                transport_type=transport,
-                auth_type=resolved_server.auth_type,
-                auth_value=auth_value,
-                auth_header_name=auth_header_name,
-                timeout=(resolved_server.timeout if resolved_server.timeout is not None else MCP_CLIENT_TIMEOUT),
-                extra_headers=extra_headers,
-                aws_auth=aws_auth,
-                sampling_callback=sampling_cb,
-                elicitation_callback=elicitation_cb,
+            return await prepare_mcp_client(
+                resolved_server,
+                MCPClient(
+                    server_url=server_url,
+                    transport_type=transport,
+                    auth_type=resolved_server.auth_type,
+                    auth_value=auth_value,
+                    auth_header_name=auth_header_name,
+                    timeout=(resolved_server.timeout if resolved_server.timeout is not None else MCP_CLIENT_TIMEOUT),
+                    extra_headers=extra_headers,
+                    aws_auth=aws_auth,
+                    sampling_callback=sampling_cb,
+                    elicitation_callback=elicitation_cb,
+                ),
             )
 
     async def _get_tools_from_server(

litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py

@@ -54,7 +54,7 @@ def sanitize_openapi_tool_name(raw_name: str) -> str:
 from litellm.proxy._experimental.mcp_server.tool_registry import (
     global_mcp_tool_registry,
 )
-from litellm.types.mcp import credential_redirect_hook, custom_credential_slot
+from litellm.types.mcp import MCPAuthType, credential_redirect_hook, custom_credential_slot
 
 
 class _OpenAPIJSONSchema(TypedDict, total=False):
@@ -471,6 +471,8 @@ def create_tool_function(
     headers: dict[str, str] | None = None,
     server_label: str | None = None,
     relays_upstream_auth: bool = False,
+    auth_type: MCPAuthType = None,
+    upstream_token_header: str | None = None,
 ):
     """Create a tool function for an OpenAPI operation.
 
@@ -503,6 +505,18 @@ async def tool_function(**kwargs: object) -> str:
         by using **kwargs instead of named parameters.
         """
         effective_headers: Final = _merge_openapi_tool_request_headers(headers)
+        if auth_type is not None:
+            from litellm.proxy._experimental.mcp_server.outbound_credentials.adapter import (
+                raise_public,
+                validate_static_credential,
+            )
+            from litellm.proxy._experimental.mcp_server.outbound_credentials.result import Error, Ok
+
+            match validate_static_credential(auth_type, effective_headers, upstream_token_header):
+                case Error(error):
+                    raise_public(error)
+                case Ok():
+                    pass
 
         # Build URL from base_url and path
         url = base_url + path

litellm/proxy/_experimental/mcp_server/outbound_credentials/adapter.py

@@ -13,15 +13,17 @@
 
 import base64
 import os
+from collections.abc import Mapping
 from typing import TYPE_CHECKING, Final, Literal, NoReturn
 
 from fastapi import HTTPException
 from pydantic import SecretStr
 from typing_extensions import assert_never
 
-from litellm.experimental_mcp_client.client import strip_auth_scheme, to_basic_credentials
+from litellm.experimental_mcp_client.client import MCPClient, strip_auth_scheme, to_basic_credentials
 from litellm.proxy._experimental.mcp_server.exceptions import MCPServerURLCredentialsError
 from litellm.proxy._experimental.mcp_server.oauth_utils import resolve_upstream_resource
+from litellm.proxy._experimental.mcp_server.outbound_credentials.result import Error, Ok, Result
 from litellm.proxy._experimental.mcp_server.outbound_credentials.types import (
     DEFAULT_CREDENTIAL_HEADER,
     ApiKeyConfig,
@@ -39,7 +41,7 @@
     Subject,
     TokenExchangeConfig,
 )
-from litellm.types.mcp import DEFAULT_SUBJECT_TOKEN_TYPE, MCPAuth
+from litellm.types.mcp import DEFAULT_SUBJECT_TOKEN_TYPE, MCPAuth, MCPAuthType, MCPTransport
 
 if TYPE_CHECKING:
     from litellm.proxy._types import UserAPIKeyAuth
@@ -79,7 +81,7 @@
 
     BYOK is the per-user source of the ``api_key`` mode; its scheme rides on ``auth_type`` just
     like a shared key, but the value is per-user and not migrated yet, so a BYOK server defers
-    to v1 regardless of ``auth_type`` (this guard is the seam the BYOK arm replaces later).
+    to v1 for its static schemes. Declared OBO always stays with the exchange arm.
 
     Dispatches on the declared ``auth_type``. The match is exhaustive over ``MCPAuthType`` with
     an ``assert_never`` tail, so a newly added auth mode fails the type gate here until it is
@@ -90,8 +92,8 @@
     modes ``true_passthrough`` / ``oauth_delegate`` (``PassthroughConfig``); delegated/passthrough
     oauth2 and SigV4 return None and stay on v1.
     """
-    if server.is_byok:
-        return None  # per-user BYOK source not migrated yet -> defer to v1 (any auth_type)
+    if server.is_byok and server.auth_type != MCPAuth.oauth2_token_exchange:
+        return None  # per-user BYOK source not migrated yet -> defer to v1
     resource: Final = server.url or server.server_id
     auth_type: Final = server.auth_type
     match auth_type:
@@ -165,21 +167,9 @@
     )
 
 
-def _token_exchange_spec(server: MCPServer, resource: str) -> ServerSpec | None:
-    """Build a token_exchange (OBO) spec, or defer (None) when it is not OBO-configured.
-
-    An OBO server with ``client_id``/``client_secret`` is owned by the v2 arm even if the
-    ``token_exchange_endpoint``/``token_url`` is absent: a missing endpoint then fails closed (412) at
-    the exchanger rather than silently deferring to v1 and connecting unauthenticated, since the
-    gateway must not guess the IdP or fall back to a weaker source. Without client credentials there is
-    nothing to own, so the server stays on v1 (parity-safe). ``profile`` selects the wire dialect
-    (``rfc8693`` default, ``entra_obo`` for Microsoft Entra On-Behalf-Of); an unrecognized value
-    normalizes to ``rfc8693`` so a bad config value cannot crash spec-building. ``audience`` is
-    forwarded only when the operator set it; a missing one is omitted, not derived.
-    """
+def _token_exchange_spec(server: MCPServer, resource: str) -> ServerSpec:
+    """Keep declared OBO owned by the resolver, including incomplete client configuration."""
     endpoint: Final = server.token_exchange_endpoint or server.effective_token_url
-    if not server.client_id or not server.client_secret:
-        return None
     profile: Final[Literal["rfc8693", "entra_obo"]] = (
         "entra_obo" if server.token_exchange_profile == "entra_obo" else "rfc8693"
     )
@@ -193,7 +183,7 @@
             token_exchange_endpoint=endpoint,
             audience=server.audience,
             client_id=server.client_id,
-            client_secret=SecretStr(server.client_secret),
+            client_secret=SecretStr(server.client_secret) if server.client_secret else None,
             token_endpoint_auth_method=server.token_endpoint_auth_method,
             scopes=tuple(server.scopes or ()),
         ),
@@ -397,3 +387,69 @@
         detail="Unauthorized",
         headers={"WWW-Authenticate": www_authenticate},
     )
+
+
+_STATIC_MODES: Final = frozenset(
+    (MCPAuth.api_key, MCPAuth.bearer_token, MCPAuth.basic, MCPAuth.token, MCPAuth.authorization)
+)
+
+
+def _usable_credential_value(auth_type: MCPAuthType, name: str, value: str) -> bool:
+    if not value:
+        return False
+    if auth_type == MCPAuth.authorization or (auth_type == MCPAuth.api_key and name != "authorization"):
+        return True
+    if value.lower() in ("bearer", "basic", "token", "apikey"):
+        return False
+    if auth_type == MCPAuth.api_key:
+        api_scheme: Final = value.split(None, 1)[0]
+        if api_scheme.lower() in ("bearer", "token", "apikey"):
+            api_credential: Final = strip_auth_scheme(value, api_scheme).strip()
+            return api_credential.lower() != api_scheme.lower()
+    if auth_type in (MCPAuth.bearer_token, MCPAuth.token):
+        scheme: Final = "Bearer" if auth_type == MCPAuth.bearer_token else "token"
+        credential: Final = strip_auth_scheme(value, scheme).strip()
+        return bool(credential) and credential.lower() != scheme.lower()
+    if auth_type == MCPAuth.basic:
+        parts: Final = value.split(None, 1)
+        if len(parts) != 2 or parts[0].lower() != "basic":
+            return False
+        try:
+            decoded: Final = base64.b64decode(parts[1], validate=True).strip()
+            return b":" in decoded
+        except ValueError:
+            return False
+    return True
+
+
+def validate_static_credential(
+    auth_type: MCPAuthType,
+    headers: Mapping[str, str],
+    upstream_token_header: str | None = None,
+) -> Result[None, CredError]:
+    if auth_type not in _STATIC_MODES:
+        return Ok(None)
+    default_slot: Final = "X-API-Key" if auth_type == MCPAuth.api_key else "Authorization"
+    slots: Final = frozenset(
+        name.lower()
+        for name in (
+            upstream_token_header or default_slot,
+            default_slot,
+            "Authorization",
+        )
+    )
+    values: Final = tuple((name.lower(), value.strip()) for name, value in headers.items() if name.lower() in slots)
+    if any(_usable_credential_value(auth_type, name, value) for name, value in values):
+        return Ok(None)
+    return Error(CredError.of_misconfigured(f"{auth_type} requires a usable upstream credential"))
+
+
+async def prepare_mcp_client(server: MCPServer, client: MCPClient) -> MCPClient:
+    if server.auth_type not in _STATIC_MODES or client.transport_type == MCPTransport.stdio:
+        return client
+    request: Final = await client.prepare_request_auth()
+    match validate_static_credential(server.auth_type, request.headers, server.upstream_token_header):
+        case Error(error):
+            raise_public(error)
+        case Ok():
+            return client

tests/test_litellm/experimental_mcp_client/test_mcp_client.py

@@ -1934,3 +1934,18 @@ def client(token: str) -> MCPClient:
     assert original != replaced
     assert len(original) == 64
     assert "private-original-credential" not in original
+
+
+@pytest.mark.asyncio
+async def test_request_auth_preview_uses_the_same_effective_headers_as_egress() -> None:
+    from litellm.proxy._experimental.mcp_server.outbound_credentials.httpx_auth import StaticHeaderAuth
+
+    client: Final = MCPClient(
+        server_url="https://upstream.example/mcp", auth_type=MCPAuth.bearer_token,
+        resolved_auth=StaticHeaderAuth("Bearer resolved"), extra_headers={"X-Trace": "trace"},
+    )
+    request: Final = await client.prepare_request_auth()
+    assert request.method == "POST"
+    assert str(request.url) == "https://upstream.example/mcp"
+    assert request.headers["Authorization"] == "Bearer resolved"
+    assert request.headers["X-Trace"] == "trace"

tests/test_litellm/proxy/_experimental/mcp_server/outbound_credentials/test_adapter.py

@@ -7,6 +7,7 @@
 
 import base64
 from types import SimpleNamespace
+from typing import Final
 
 import pytest
 from fastapi import HTTPException
@@ -20,7 +21,9 @@
     raise_user_oauth_challenge,
     to_server_spec,
     to_subject,
+    validate_static_credential,
 )
+from litellm.proxy._experimental.mcp_server.outbound_credentials.result import Ok
 from litellm.proxy._experimental.mcp_server.outbound_credentials.types import (
     ApiKeyConfig,
     AuthorizationCodeConfig,
@@ -34,10 +37,28 @@
     SharedKey,
     TokenExchangeConfig,
 )
-from litellm.types.mcp import MCPAuth, MCPTransport
+from litellm.types.mcp import MCPAuth, MCPAuthType, MCPTransport
 from litellm.types.mcp_server.mcp_server_manager import MCPServer
 
 
+@pytest.mark.parametrize("auth_type,header,value", [
+    (MCPAuth.api_key, "Authorization", "Bearer fixture-key"),
+    (MCPAuth.api_key, "Authorization", "ApiKey fixture-key"),
+    (MCPAuth.api_key, "Authorization", "token fixture-key"),
+    (MCPAuth.api_key, "Authorization", "Bearer token"),
+    (MCPAuth.api_key, "Authorization", "opaque-key"),
+    (MCPAuth.api_key, "Authorization", "Custom Custom"),
+    (MCPAuth.api_key, "X-API-Key", "Bearer Bearer"),
+    (MCPAuth.api_key, "X-Custom", "ApiKey ApiKey"),
+    (MCPAuth.authorization, "Authorization", "Bearer Bearer"),
+])
+def test_static_credential_preserves_supported_api_key_and_raw_headers(
+    auth_type: MCPAuthType, header: str, value: str,
+) -> None:
+    result: Final = validate_static_credential(auth_type, {header: value}, upstream_token_header=header)
+    assert isinstance(result, Ok)
+
+
 def _server(**kwargs) -> MCPServer:
     return MCPServer(server_id="s", name="n", transport=MCPTransport.http, **kwargs)
 
@@ -155,12 +176,6 @@ def test_oauth2_user_token_maps_to_authorization_code(oauth2_flow):
         _server(auth_type=MCPAuth.api_key),  # no token configured
         _server(auth_type=MCPAuth.bearer_token),  # no token configured
         _server(auth_type=MCPAuth.oauth2, delegate_auth_to_upstream=True),  # delegated upstream OAuth -> v1
-        _server(auth_type=MCPAuth.oauth2_token_exchange),  # no endpoint/client creds -> incomplete -> v1
-        _server(
-            auth_type=MCPAuth.oauth2_token_exchange,
-            token_exchange_endpoint="https://idp/token",
-            client_id="cid",
-        ),  # missing client_secret -> incomplete -> v1
         _server(auth_type=MCPAuth.aws_sigv4),
         _server(auth_type=None, oauth_passthrough=True, extra_headers=["Authorization"]),
     ],
@@ -802,3 +817,14 @@ def test_a_blank_header_name_means_unset_rather_than_an_error(blank):
     spec = to_server_spec(server)
     assert spec is not None
     assert spec.config.header_name == "Authorization"
+
+
+@pytest.mark.parametrize("client_secret", [None, ""])
+@pytest.mark.parametrize("is_byok", [False, True])
+def test_incomplete_obo_keeps_exchange_ownership(client_secret: str | None, is_byok: bool) -> None:
+    spec = to_server_spec(_server(auth_type=MCPAuth.oauth2_token_exchange, client_id="client",
+                                  client_secret=client_secret, is_byok=is_byok))
+    assert spec is not None
+    assert isinstance(spec.config, TokenExchangeConfig)
+    assert spec.config.client_id == "client"
+    assert spec.config.client_secret is None