diff --git a/litellm/proxy/mcp_server/catalog.py b/litellm/proxy/mcp_server/catalog.py index d2ff322ba5c..9897ded8ab2 100644 --- a/litellm/proxy/mcp_server/catalog.py +++ b/litellm/proxy/mcp_server/catalog.py @@ -23,6 +23,8 @@ from pydantic import BaseModel, ConfigDict, JsonValue, TypeAdapter from litellm._logging import verbose_logger from litellm.caching.in_memory_cache import InMemoryCache +from litellm.proxy.mcp_server.exceptions import MCPUpstreamAuthError +from litellm.proxy.mcp_server.legacy_callbacks import get_scope_response from litellm.proxy.mcp_server.result_conversion import age_freshness, aggregate_freshness if TYPE_CHECKING: @@ -943,12 +945,9 @@ async def get_filtered_server_tools( ) return page.model_copy(update={"tools": filtered_tools}), ServerListOk(tool_count=len(filtered_tools)) except MCPUpstreamAuthError as e: - # Absorb so one unauthenticated server does not empty every other server's - # tools. Surfacing the upstream 401 to the client as a re-auth challenge is - # intentionally not done here: raising from this list handler cannot produce a - # 401 + WWW-Authenticate (the MCP session manager serializes it as a JSON-RPC - # error). Single-server routes surface it via the request-scope preemptive - # check in _raise_preemptive_401_for_unauthenticated_servers instead. + scope_response: Final = get_scope_response() + if scope_response is not None and len(allowed_mcp_servers) == 1: + scope_response.deny(e) verbose_logger.debug("MCP list_tools: omitting %s; it needs upstream auth", server.name) return ListToolsResult(tools=[]), classify_list_exception(e) except Exception as e: @@ -1199,6 +1198,10 @@ async def list_gateway_catalog( update={"meta": {key: value for key, value in page_meta.items() if key != SERVER_OUTCOMES_META_KEY}} ) except Exception as error: + if isinstance(error, MCPUpstreamAuthError): + scope_response: Final = get_scope_response() + if scope_response is not None and len(allowed) == 1: + scope_response.deny(error) if cursor is not None: raise MCPError( code=INVALID_PARAMS, message="Upstream continuation failed; start a fresh listing" diff --git a/litellm/proxy/mcp_server/mcp_server_manager.py b/litellm/proxy/mcp_server/mcp_server_manager.py index eacba25257e..5cf5cad35f5 100644 --- a/litellm/proxy/mcp_server/mcp_server_manager.py +++ b/litellm/proxy/mcp_server/mcp_server_manager.py @@ -7164,10 +7164,14 @@ class MCPServerManager: scope_response: Final = get_scope_response() if scope_response is not None and not ( - mcp_server.is_gateway_managed_oauth2 - and mcp_server.needs_user_oauth_token - and not mcp_server.spec_path - and mcp_server.transport in (MCPTransport.http, MCPTransport.sse) + ( + mcp_server.is_gateway_managed_oauth2 + and mcp_server.needs_user_oauth_token + and not mcp_server.spec_path + and mcp_server.transport in (MCPTransport.http, MCPTransport.sse) + ) + or mcp_server.is_oauth_passthrough + or mcp_server.delegate_auth_to_upstream ): scope_response.allow() diff --git a/litellm/proxy/mcp_server/scope_challenge.py b/litellm/proxy/mcp_server/scope_challenge.py index 128b27b0f91..14ed72cb864 100644 --- a/litellm/proxy/mcp_server/scope_challenge.py +++ b/litellm/proxy/mcp_server/scope_challenge.py @@ -44,7 +44,10 @@ class OAuthScopeResponse: self._ready.set() def deny(self, error: MCPUpstreamAuthError) -> None: - if self.pending and error.status_code == 403 and error.required_scope is not None: + if self.pending and ( + error.status_code == 401 + or (error.status_code == 403 and error.required_scope is not None) + ): self._challenge = error self._ready.set() diff --git a/litellm/proxy/mcp_server/server.py b/litellm/proxy/mcp_server/server.py index bbbbd09e527..8caf7f61158 100644 --- a/litellm/proxy/mcp_server/server.py +++ b/litellm/proxy/mcp_server/server.py @@ -2644,7 +2644,10 @@ if MCP_AVAILABLE: get_request_base_url(StarletteRequest(scope)), get_route_relative_request_path(scope), ) - if is_tool_call_request(body) or len(body) >= _MCP_ROUTING_PEEK_MAX_BYTES + if scoped_server_endpoint + or (mcp_servers is not None and len(mcp_servers) == 1) + or is_tool_call_request(body) + or len(body) >= _MCP_ROUTING_PEEK_MAX_BYTES else None ) if scope_response is not None: diff --git a/tests/unit/proxy/mcp_server/test_mcp_oauth_passthrough_tools.py b/tests/unit/proxy/mcp_server/test_mcp_oauth_passthrough_tools.py index 03a7373c908..43c07d39717 100644 --- a/tests/unit/proxy/mcp_server/test_mcp_oauth_passthrough_tools.py +++ b/tests/unit/proxy/mcp_server/test_mcp_oauth_passthrough_tools.py @@ -341,7 +341,6 @@ async def test_aggregate_list_tools_absorbs_one_unauthenticated_server(): from mcp.types import Tool as MCPTool from litellm.proxy._types import UserAPIKeyAuth - from litellm.proxy.mcp_server import server as mcp_server delegate = _http_server( "s1", "delegate_docs", auth_type=MCPAuth.oauth2, delegate_auth_to_upstream=True @@ -384,7 +383,6 @@ async def test_single_server_route_also_absorbs_upstream_auth_error(): from unittest.mock import patch from litellm.proxy._types import UserAPIKeyAuth - from litellm.proxy.mcp_server import server as mcp_server from litellm.proxy.mcp_server.mcp_context import mcp_gateway_server_name delegate = _http_server( @@ -425,7 +423,6 @@ async def test_aggregate_with_single_accessible_server_still_absorbs(): from unittest.mock import patch from litellm.proxy._types import UserAPIKeyAuth - from litellm.proxy.mcp_server import server as mcp_server delegate = _http_server( "s1", "delegate_docs", auth_type=MCPAuth.oauth2, delegate_auth_to_upstream=True @@ -836,3 +833,102 @@ def test_managed_step_up_metadata_matches_the_sdk_configured_resource(path): requested_resource=f"https://gateway.test{path}", configured_resource=f"https://gateway.test{resource_path}", ), "the SDK must accept the advertised resource before it can reauthorize" + + +@pytest.mark.asyncio +async def test_scope_challenge_replaces_pending_stream_headers_on_401(): + from litellm.proxy.mcp_server.scope_challenge import OAuthScopeResponse + + send = AsyncMock() + response = OAuthScopeResponse(send, "https://gateway.example", "/mcp/docs") + headers: Final = asyncio.create_task(response({"type": "http.response.start", "status": 200, "headers": []})) + body = asyncio.create_task(response({"type": "http.response.body", "body": b"event: message\n"})) + await asyncio.sleep(0) + send.assert_not_awaited() + response.deny(MCPUpstreamAuthError(401, None, "docs")) + await asyncio.wait_for(asyncio.gather(headers, body), 1) + await response({"type": "http.response.body", "body": b"tools result"}) + assert send.await_count == 2 + start, result = [call.args[0] for call in send.await_args_list] + assert start["status"] == 401 + challenge = dict(start["headers"])[b"www-authenticate"].decode() + assert challenge == 'Bearer resource_metadata="https://gateway.example/.well-known/oauth-protected-resource/mcp/docs"' + assert result["body"] == b'{"detail":"Unauthorized"}' + + +@pytest.mark.asyncio +async def test_get_filtered_server_tools_denies_scope_response_on_single_server_401(): + from unittest.mock import MagicMock, patch + + from mcp.server.context import ServerRequestContext + from starlette.requests import Request + + from litellm.proxy.mcp_server.catalog import get_filtered_server_tools + from litellm.proxy.mcp_server.contracts import OperationContext + from litellm.proxy.mcp_server.mcp_context import active_mcp_request_ctx_var + from litellm.proxy.mcp_server.scope_challenge import SCOPE_RESPONSE_KEY, OAuthScopeResponse + + mock_send = AsyncMock() + scope_response = OAuthScopeResponse(mock_send, "https://gateway.example", "/mcp/docs") + request = Request({"type": "http", SCOPE_RESPONSE_KEY: scope_response}) + context = ServerRequestContext(session=MagicMock(), lifespan_context={}, protocol_version="2025-11-25", method="tools/list", request=request) + token = active_mcp_request_ctx_var.set(context) + + server = _http_server("s1", "docs", auth_type=MCPAuth.none, extra_headers=["Authorization"], oauth_passthrough=True) + op_ctx = OperationContext(_caller=None, mcp_servers=("docs",)) + + try: + with patch("litellm.proxy.mcp_server.operations.global_mcp_server_manager.get_tools_from_server", + AsyncMock(side_effect=MCPUpstreamAuthError(401, None, "docs"))): + tools_result, outcome = await get_filtered_server_tools( + server, + context=op_ctx, + allowed_mcp_servers=[server], + prefetched_oauth_creds={}, + ) + assert tools_result.tools == [] + assert outcome.tag == "auth_required" + assert not scope_response.pending + assert scope_response._challenge is not None + assert scope_response._challenge.status_code == 401 + finally: + active_mcp_request_ctx_var.reset(token) + + +@pytest.mark.asyncio +async def test_get_filtered_server_tools_does_not_deny_scope_response_on_multi_server_401(): + from unittest.mock import MagicMock, patch + + from mcp.server.context import ServerRequestContext + from starlette.requests import Request + + from litellm.proxy.mcp_server.catalog import get_filtered_server_tools + from litellm.proxy.mcp_server.contracts import OperationContext + from litellm.proxy.mcp_server.mcp_context import active_mcp_request_ctx_var + from litellm.proxy.mcp_server.scope_challenge import SCOPE_RESPONSE_KEY, OAuthScopeResponse + + mock_send = AsyncMock() + scope_response = OAuthScopeResponse(mock_send, "https://gateway.example", "/mcp") + request = Request({"type": "http", SCOPE_RESPONSE_KEY: scope_response}) + context = ServerRequestContext(session=MagicMock(), lifespan_context={}, protocol_version="2025-11-25", method="tools/list", request=request) + token = active_mcp_request_ctx_var.set(context) + + server1 = _http_server("s1", "docs", auth_type=MCPAuth.none, extra_headers=["Authorization"], oauth_passthrough=True) + server2 = _http_server("s2", "other", auth_type=MCPAuth.none) + op_ctx = OperationContext(_caller=None, mcp_servers=("docs", "other")) + + try: + with patch("litellm.proxy.mcp_server.operations.global_mcp_server_manager.get_tools_from_server", + AsyncMock(side_effect=MCPUpstreamAuthError(401, None, "docs"))): + tools_result, outcome = await get_filtered_server_tools( + server1, + context=op_ctx, + allowed_mcp_servers=[server1, server2], + prefetched_oauth_creds={}, + ) + assert tools_result.tools == [] + assert outcome.tag == "auth_required" + assert scope_response.pending + assert scope_response._challenge is None + finally: + active_mcp_request_ctx_var.reset(token)