Support MCP OAuth passthrough and issuer-scoped JWT auth

litellm/experimental_mcp_client/client.py

@@ -421,8 +421,16 @@ def factory(
 
         return factory
 
-    async def list_tools(self) -> List[MCPTool]:
-        """List available tools from the server."""
+    async def list_tools(self, raise_on_error: bool = False) -> List[MCPTool]:
+        """List available tools from the server.
+
+        Args:
+            raise_on_error: When True, re-raise exceptions instead of returning
+                an empty list. Used by the proxy's pass-through MCP flow so it
+                can surface upstream HTTP 401 responses as a proper 401 to the
+                MCP client (triggering the upstream OAuth flow) rather than
+                masking them as "connected, no tools".
+        """
         verbose_logger.debug(
             f"MCP client listing tools from {self.server_url or 'stdio'}"
         )
@@ -458,6 +466,8 @@ async def _list_tools_operation(session: ClientSession):
                     "the MCP server may have crashed, disconnected, or timed out"
                 )
 
+            if raise_on_error:
+                raise
             # Return empty list instead of raising to allow graceful degradation
             return []
 

litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py

@@ -14,6 +14,59 @@
     UserAPIKeyAuth,
 )
 from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
+from litellm.proxy.auth.ip_address_utils import IPAddressUtils
+
+
+def _parse_mcp_server_names_from_path(path: str) -> Optional[List[str]]:
+    """Parse a single MCP server name from /mcp/{name} or /{name}/mcp path patterns.
+    Returns None for the aggregate /mcp route (no bypass for multi-server paths)."""
+    m = re.match(r"^/mcp/([^/,?#]+)", path)
+    if m:
+        return [m.group(1)]
+    m = re.match(r"^/([^/,?#]+)/mcp", path)
+    if m:
+        return [m.group(1)]
+    return None
+
+
+def _is_mcp_passthrough_cold_start(
+    scope: Scope, mcp_servers: Optional[List[str]], client_ip: Optional[str]
+) -> bool:
+    """True when the request targets a pass-through server with no auth headers —
+    the cold-start OAuth discovery case per RFC 9728 / MCP Authorization spec.
+    Lets the route handler's 401 emitter produce the spec-compliant WWW-Authenticate
+    challenge instead of surfacing a generic admission error."""
+    if not mcp_servers:
+        return False
+    from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
+        global_mcp_server_manager,
+    )
+
+    for name in mcp_servers:
+        server = global_mcp_server_manager.get_mcp_server_by_name(
+            name, client_ip=client_ip
+        )
+        if server is not None and getattr(server, "is_oauth_passthrough", False):
+            return True
+    return False
+
+
+def _is_litellm_auth_admission_error(exc: Exception) -> bool:
+    if isinstance(exc, HTTPException):
+        return exc.status_code == 401
+    if isinstance(exc, ProxyException):
+        try:
+            return int(exc.code) == 401
+        except (TypeError, ValueError):
+            return False
+    return False
+
+
+def _has_client_supplied_mcp_auth(
+    mcp_auth_header: Optional[str],
+    mcp_server_auth_headers: Dict[str, Dict[str, str]],
+) -> bool:
+    return bool(mcp_auth_header) or bool(mcp_server_auth_headers)
 
 
 class MCPRequestHandler:
@@ -37,7 +90,7 @@ class MCPRequestHandler:
     LITELLM_MCP_ACCESS_GROUPS_HEADER_NAME = SpecialHeaders.mcp_access_groups.value
 
     @staticmethod
-    async def process_mcp_request(
+    async def process_mcp_request(  # noqa: PLR0915
         scope: Scope,
     ) -> Tuple[
         UserAPIKeyAuth,
@@ -126,7 +179,9 @@ async def mock_body():
         elif (
             not litellm_api_key
             and MCPRequestHandler._target_servers_delegate_auth_to_upstream(  # noqa: E501
-                path=request.url.path, mcp_servers=mcp_servers
+                path=request.url.path,
+                mcp_servers=mcp_servers,
+                client_ip=IPAddressUtils.get_mcp_client_ip(request),
             )
         ):
             # Operator opted this oauth2 server into upstream-delegated auth
@@ -174,7 +229,9 @@ async def mock_body():
                     "401",
                     "403",
                 ) and MCPRequestHandler._target_servers_use_oauth2(
-                    path=request.url.path, mcp_servers=mcp_servers
+                    path=request.url.path,
+                    mcp_servers=mcp_servers,
+                    client_ip=IPAddressUtils.get_mcp_client_ip(request),
                 ):
                     verbose_logger.debug(
                         "MCP OAuth2: target server is OAuth2-mode, treating "
@@ -184,9 +241,35 @@ async def mock_body():
                 else:
                     raise
         else:
-            validated_user_api_key_auth = await user_api_key_auth(
-                api_key=litellm_api_key, request=request
-            )
+            try:
+                validated_user_api_key_auth = await user_api_key_auth(
+                    api_key=litellm_api_key, request=request
+                )
+            except (HTTPException, ProxyException) as exc:
+                # Cold-start MCP OAuth discovery: RFC 9728 / MCP Authorization spec
+                # require unauthenticated requests to protected resources to receive
+                # 401 + WWW-Authenticate. Defer to _raise_preemptive_401_for_unauthenticated_servers
+                # for pass-through servers instead of surfacing a generic admission error.
+                path = scope.get("path", "")
+                mcp_servers_from_path = _parse_mcp_server_names_from_path(path)
+                client_ip = IPAddressUtils.get_mcp_client_ip(request)
+                if (
+                    mcp_servers_from_path is not None
+                    and not _has_client_supplied_mcp_auth(
+                        mcp_auth_header,
+                        mcp_server_auth_headers,
+                    )
+                    and _is_litellm_auth_admission_error(exc)
+                    and _is_mcp_passthrough_cold_start(
+                        scope, mcp_servers_from_path, client_ip=client_ip
+                    )
+                ):
+                    verbose_logger.debug(
+                        "MCP pass-through cold start: deferring admission to route 401 emitter"
+                    )
+                    validated_user_api_key_auth = UserAPIKeyAuth()
+                else:
+                    raise
 
         return (
             validated_user_api_key_auth,
@@ -258,7 +341,9 @@ def _extract_target_server_names_from_path(path: str) -> List[str]:
         return [servers_and_path]
 
     @staticmethod
-    def _target_servers_use_oauth2(path: str, mcp_servers: Optional[List[str]]) -> bool:
+    def _target_servers_use_oauth2(
+        path: str, mcp_servers: Optional[List[str]], client_ip: Optional[str]
+    ) -> bool:
         """
         True only when EVERY MCP server the request targets is configured for
         ``auth_type == oauth2``. If any target is non-OAuth2 — or if the target
@@ -287,14 +372,16 @@ def _target_servers_use_oauth2(path: str, mcp_servers: Optional[List[str]]) -> b
             return False
 
         for name in target_names:
-            server = global_mcp_server_manager.get_mcp_server_by_name(name)
+            server = global_mcp_server_manager.get_mcp_server_by_name(
+                name, client_ip=client_ip
+            )
             if server is None or server.auth_type != MCPAuth.oauth2:
                 return False
         return True
 
     @staticmethod
     def _target_servers_delegate_auth_to_upstream(
-        path: str, mcp_servers: Optional[List[str]]
+        path: str, mcp_servers: Optional[List[str]], client_ip: Optional[str]
     ) -> bool:
         """
         True only when EVERY MCP server the request targets is configured for
@@ -324,7 +411,9 @@ def _target_servers_delegate_auth_to_upstream(
             return False
 
         for name in target_names:
-            server = global_mcp_server_manager.get_mcp_server_by_name(name)
+            server = global_mcp_server_manager.get_mcp_server_by_name(
+                name, client_ip=client_ip
+            )
             if server is None or server.auth_type != MCPAuth.oauth2:
                 return False
             # `is True` is intentional: opt-in must be an explicit boolean