diff --git a/litellm/proxy/mcp_server/mcp_server_manager.py b/litellm/proxy/mcp_server/mcp_server_manager.py index d31e9246a38..965bb359b67 100644 --- a/litellm/proxy/mcp_server/mcp_server_manager.py +++ b/litellm/proxy/mcp_server/mcp_server_manager.py @@ -159,6 +159,7 @@ from litellm.proxy.mcp_server.outbound_credentials.token_exchange_provider impor ) from litellm.proxy.mcp_server.outbound_credentials.types import ( DEFAULT_CREDENTIAL_HEADER, + ApiKeyConfig, AuthResolution, IdJagConfig, PassthroughConfig, @@ -1346,6 +1347,47 @@ def _server_auth_header_for( return mcp_auth_header if server_specific is None else server_specific +def _v1_default_key_header(auth_type: MCPAuthType) -> str | None: + match auth_type: + case ( + MCPAuth.bearer_token + | MCPAuth.basic + | MCPAuth.authorization + | MCPAuth.oauth2 + | MCPAuth.token + | MCPAuth.oauth2_token_exchange + ): + return "Authorization" + case MCPAuth.api_key: + return "X-API-Key" + case ( + None + | MCPAuth.none + | MCPAuth.aws_sigv4 + | MCPAuth.oauth2_id_jag + | MCPAuth.true_passthrough + | MCPAuth.oauth_delegate + ): + return None + assert_never(auth_type) # pragma: no cover + + +def _v1_key_occupies_authorization(server: MCPServer) -> bool: + if server.is_byok or not server.authentication_token: + return False + default_header: Final = _v1_default_key_header(server.auth_type) + if default_header is None: + return False + return (server.upstream_token_header or default_header).lower() == "authorization" + + +def _server_key_occupies_authorization(server: MCPServer) -> bool: + spec: Final = to_server_spec(server) + if spec is None: + return _v1_key_occupies_authorization(server) + return isinstance(spec.config, ApiKeyConfig) and spec.config.header_name.lower() == "authorization" + + def listed_tools_caller_for( server: MCPServer, user_api_key_auth: UserAPIKeyAuth | None, @@ -4604,6 +4646,7 @@ class MCPServerManager: and not has_static_authorization and not mcp_auth_header and not has_extra_authorization + and not _server_key_occupies_authorization(server) ): extra_headers = await inject_mcp_jwt_headers_for_upstream( user_api_key_dict=user_api_key_auth, @@ -6888,9 +6931,11 @@ class MCPServerManager: hook_has_authorization: Final = any(k.lower() == "authorization" for k in hook_extra_headers) existing_has_authorization: Final = any(k.lower() == "authorization" for k in extra_headers) server_auth_occupies_authorization: Final = ( - any(k.lower() == "authorization" for k in server_auth_header) + _server_key_occupies_authorization(mcp_server) + if not server_auth_header + else any(k.lower() == "authorization" for k in server_auth_header) if isinstance(server_auth_header, dict) - else server_auth_header is not None and mcp_server.auth_type != MCPAuth.api_key + else mcp_server.auth_type != MCPAuth.api_key ) if hook_has_authorization and (existing_has_authorization or server_auth_occupies_authorization): # Mirror the tools/list signer guard: an upstream credential (user OAuth, diff --git a/tests/unit/proxy/mcp_server/test_mcp_server_manager.py b/tests/unit/proxy/mcp_server/test_mcp_server_manager.py index 13190791cc7..2c9f29255d9 100644 --- a/tests/unit/proxy/mcp_server/test_mcp_server_manager.py +++ b/tests/unit/proxy/mcp_server/test_mcp_server_manager.py @@ -80,6 +80,7 @@ from litellm.proxy.mcp_server.mcp_server_manager import ( _mcp_oauth_discovery_on_startup_enabled, _normalize_mcp_server_cost_info, _obo_retry_applies, + _server_key_occupies_authorization, global_mcp_server_manager, listed_tools_caller_for, oauth_endpoints_unresolved, @@ -230,9 +231,7 @@ async def test_sampling_callbacks_isolate_callers_and_cancellation(): _create_sampling_callback(UserAPIKeyAuth(user_id=label), raw_headers={"x-caller": label}) for label in ("alpha", "bravo", "cancelled") ) - with patch( - "litellm.proxy.mcp_server.sampling_handler.handle_sampling_create_message", record_sampling - ): + with patch("litellm.proxy.mcp_server.sampling_handler.handle_sampling_create_message", record_sampling): tasks = tuple(asyncio.create_task(callback(None, None)) for callback in callbacks) await asyncio.wait_for(started.wait(), timeout=2) tasks[2].cancel() @@ -6609,9 +6608,7 @@ class TestMCPServerManager: @pytest.mark.asyncio @pytest.mark.parametrize("tool_name,denied", [("tool1", False), ("tool2", True), ("tool3", True)]) - async def test_pre_call_tool_check_disallowed_tools_takes_precedence( - self, tool_name: str, denied: bool - ) -> None: + async def test_pre_call_tool_check_disallowed_tools_takes_precedence(self, tool_name: str, denied: bool) -> None: manager: Final = MCPServerManager() server: Final = MCPServer( server_id="test-server", @@ -8289,7 +8286,9 @@ class TestMCPServerManager: user = UserAPIKeyAuth(api_key="sk-litellm", user_id="byok-cold-user") manager.create_mcp_client = AsyncMock(return_value=_listing_client()) manager._fetch_tools_with_timeout = AsyncMock( - return_value=ListToolsResult(tools=[MCPTool(name="turn", description="listed while db down", inputSchema={})]) + return_value=ListToolsResult( + tools=[MCPTool(name="turn", description="listed while db down", inputSchema={})] + ) ) with ( @@ -8341,7 +8340,9 @@ class TestMCPServerManager: mock_client.call_tool.return_value = MagicMock(spec=CallToolResult, content=[], isError=False) manager.create_mcp_client = AsyncMock(return_value=mock_client) manager._fetch_tools_with_timeout = AsyncMock( - return_value=ListToolsResult(tools=[MCPTool(name="turn", description="stored cred catalog", inputSchema={})]) + return_value=ListToolsResult( + tools=[MCPTool(name="turn", description="stored cred catalog", inputSchema={})] + ) ) proxy_logging_obj = _mock_proxy_logging() proxy_logging_obj.create_mcp_request_object_from_kwargs = MagicMock(return_value={}) @@ -8664,7 +8665,9 @@ class TestMCPServerManager: mock_client: Final = _listing_client() mock_client.call_tool.return_value = MagicMock(spec=CallToolResult, content=[], isError=False) manager.create_mcp_client = AsyncMock(return_value=mock_client) - manager._fetch_tools_with_timeout = AsyncMock(side_effect=lambda client, name: ListToolsResult(tools=catalogs[client.workspace])) + manager._fetch_tools_with_timeout = AsyncMock( + side_effect=lambda client, name: ListToolsResult(tools=catalogs[client.workspace]) + ) for workspace in ("A", "B"): manager.create_mcp_client.return_value.workspace = workspace await manager._get_tools_from_server( @@ -17382,6 +17385,156 @@ async def test_tools_list_signed_by_the_gateway_jwt_signer_is_fetched_every_time assert sum(method == "tools/list" for method, _auth in upstream.requests) == 2 +_GATEWAY_JWT: Final = "Bearer signed-by-the-gateway" + +_SERVER_KEY_CASES: Final = ( + pytest.param(MCPAuth.bearer_token, "server-key", None, "Bearer server-key", id="bearer_token"), + pytest.param(MCPAuth.token, "server-key", None, "token server-key", id="token"), + pytest.param(MCPAuth.authorization, "server-key", None, "server-key", id="authorization"), + pytest.param(MCPAuth.basic, "user:pass", None, "Basic dXNlcjpwYXNz", id="basic"), + pytest.param(MCPAuth.api_key, "server-key", None, _GATEWAY_JWT, id="api_key-keeps-signer"), + pytest.param(MCPAuth.bearer_token, "server-key", "X-Upstream-Key", _GATEWAY_JWT, id="custom-header-keeps-signer"), + pytest.param(MCPAuth.bearer_token, None, None, _GATEWAY_JWT, id="no-key-keeps-signer"), + pytest.param(MCPAuth.oauth2, "server-key", None, "Bearer server-key", id="oauth2-delegate-static-token"), + pytest.param(MCPAuth.oauth2, None, None, _GATEWAY_JWT, id="oauth2-delegate-no-key-keeps-signer"), + pytest.param( + MCPAuth.oauth2, "server-key", "X-Upstream-Key", _GATEWAY_JWT, id="oauth2-delegate-custom-header-keeps-signer" + ), +) + + +def _keyed_server(base: MCPServer, auth_type: MCPAuth, key: str | None, token_header: str | None) -> MCPServer: + return base.model_copy( + update={ + "auth_type": auth_type, + "authentication_token": key, + "upstream_token_header": token_header, + "delegate_auth_to_upstream": auth_type == MCPAuth.oauth2, + } + ) + + +@pytest.mark.parametrize("token_header", [None, "Authorization"], ids=["default-header", "authorization-override"]) +def test_a_sigv4_server_token_leaves_authorization_free_for_the_jwt_signer(token_header: str | None) -> None: + server: Final = _keyed_server(_server_with_tools_list_ttl(300), MCPAuth.aws_sigv4, "server-key", token_header) + + assert _server_key_occupies_authorization(server) is False + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("auth_type", "key", "token_header", "expected_authorization"), _SERVER_KEY_CASES) +async def test_tools_list_keeps_the_server_key_in_authorization_when_the_jwt_signer_is_on( + monkeypatch: pytest.MonkeyPatch, + auth_type: MCPAuth, + key: str | None, + token_header: str | None, + expected_authorization: str, +) -> None: + from litellm.proxy.guardrails.guardrail_hooks.mcp_jwt_signer import mcp_jwt_signer + + class _Signer: + async def async_pre_call_hook( + self, user_api_key_dict: UserAPIKeyAuth | None, cache: object, data: object, call_type: str + ) -> Mapping[str, object]: + return {"extra_headers": {"Authorization": _GATEWAY_JWT}} + + monkeypatch.setattr(mcp_jwt_signer, "_mcp_jwt_signer_instance", _Signer(), raising=False) + upstream: Final = _DiscoveryUpstream() + caller: Final = UserAPIKeyAuth(api_key="hashed-caller", user_id="caller") + with _mcp_upstream(upstream.respond): + await _list_discovery_tools( + MCPServerManager(discovery_clock=_DiscoveryClock()), + server=_keyed_server(_server_with_tools_list_ttl(300), auth_type, key, token_header), + user_api_key_auth=caller, + ) + assert {auth for method, auth in upstream.requests if method == "tools/list"} == {expected_authorization} + + +async def _tools_call_authorizations( + server: MCPServer, + mcp_auth_header: str | None = None, + mcp_server_auth_headers: dict[str, dict[str, str]] | None = None, +) -> list[str]: + from mcp.types import JSONRPCRequest + + tool_call_authorizations: list[str] = [] # mutable-ok: the mock upstream appends what each tools/call carried + + async def respond(request: httpx2.Request) -> httpx2.Response: + if request.method == "DELETE": + return httpx2.Response(200) + payload: Final = _JSONRPC_ADAPTER.validate_json(request.content) + if not isinstance(payload, JSONRPCRequest): + return httpx2.Response(202) + if payload.method == "tools/call": + tool_call_authorizations.append(request.headers.get("authorization", "")) + return httpx2.Response( + 200, json={"jsonrpc": "2.0", "id": payload.id, "result": {"content": [], "isError": False}} + ) + if payload.method == "tools/list": + return httpx2.Response(200, json={"jsonrpc": "2.0", "id": payload.id, "result": {"tools": []}}) + return httpx2.Response( + 200, + json={ + "jsonrpc": "2.0", + "id": payload.id, + "result": { + "protocolVersion": "2025-03-26", + "serverInfo": {"name": "upstream", "version": "1"}, + "capabilities": {"tools": {}}, + }, + }, + ) + + manager: Final = MCPServerManager(upstream_transport=httpx2.MockTransport(respond)) + await manager._call_regular_mcp_tool( + mcp_server=server, + original_tool_name="example", + arguments={}, + tasks=[], + mcp_auth_header=mcp_auth_header, + mcp_server_auth_headers=mcp_server_auth_headers, + oauth2_headers=None, + raw_headers=None, + proxy_logging_obj=None, + hook_extra_headers={"Authorization": _GATEWAY_JWT}, + user_api_key_auth=UserAPIKeyAuth(api_key="hashed-caller", user_id="caller"), + ) + return tool_call_authorizations + + +_KEYED_BASE: Final = MCPServer( + server_id="keyed", name="keyed", alias="keyed", url="https://keyed.example/mcp", transport=MCPTransport.http +) + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("auth_type", "key", "token_header", "expected_authorization"), _SERVER_KEY_CASES) +async def test_tools_call_keeps_the_server_key_in_authorization_when_the_jwt_signer_is_on( + auth_type: MCPAuth, key: str | None, token_header: str | None, expected_authorization: str +) -> None: + server: Final = _keyed_server(_KEYED_BASE, auth_type, key, token_header) + + assert await _tools_call_authorizations(server) == [expected_authorization] + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("auth_type", "caller_auth", "caller_server_headers"), + [ + pytest.param(MCPAuth.api_key, "caller-key", None, id="api_key-caller-key-goes-to-x-api-key"), + pytest.param( + MCPAuth.bearer_token, None, {"keyed": {"X-Custom": "caller"}}, id="caller-headers-without-authorization" + ), + ], +) +async def test_tools_call_keeps_the_signer_when_the_caller_auth_displaces_the_server_key( + auth_type: MCPAuth, caller_auth: str | None, caller_server_headers: dict[str, dict[str, str]] | None +) -> None: + server: Final = _keyed_server(_KEYED_BASE, auth_type, "server-key", "Authorization") + + assert await _tools_call_authorizations(server, caller_auth, caller_server_headers) == [_GATEWAY_JWT] + + @pytest.mark.asyncio async def test_tools_list_cache_keeps_two_litellm_callers_apart_behind_one_upstream_credential() -> None: manager: Final = MCPServerManager(discovery_clock=_DiscoveryClock()) @@ -22015,7 +22168,7 @@ async def test_catalog_page_registers_bare_routes_only_for_complete_initial_disc manager._create_prefixed_tools([LIST_NOTES], other) manager.create_mcp_client.return_value = SimpleNamespace( discovery_auth_fingerprint=AsyncMock(return_value="test-credential-hash"), - list_tools_page=AsyncMock(return_value=ListToolsResult(tools=[LIST_NOTES], next_cursor=next_cursor)) + list_tools_page=AsyncMock(return_value=ListToolsResult(tools=[LIST_NOTES], next_cursor=next_cursor)), ) result = await manager.get_tools_page(server, params=PaginatedRequestParams(cursor=request_cursor)) @@ -22632,9 +22785,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.mcp_server.mcp_server_manager.MCP_TOOL_LISTING_TIMEOUT", 0.5 - ) + monkeypatch.setattr("litellm.proxy.mcp_server.mcp_server_manager.MCP_TOOL_LISTING_TIMEOUT", 0.5) manager: Final = MCPServerManager() client: Final = MagicMock() client.list_tools_result = AsyncMock(side_effect=_upstream_http_status_error(429, {"Retry-After": "5"})) @@ -22676,9 +22827,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.mcp_server.mcp_server_manager.MCP_TOOL_LISTING_TIMEOUT", 0.05 - ) + monkeypatch.setattr("litellm.proxy.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}