fix(mcp): keep an MCP server's own Authorization key when the JWT signer is on (#51867)

* fix(mcp): keep an MCP server's own Authorization key when the JWT signer is on

With mcp_jwt_signer enabled, a server whose configured authentication_token is sent in
Authorization (bearer_token, token, authorization, basic) had that key replaced by the
signer's JWT on tools/list and tools/call, so the upstream returned 401. Both signer guards
now also treat the server's own key as occupying Authorization, using the same
to_server_spec mapping that sends the key upstream.

Resolves LIT-10782
Fixes #47988

Co-authored-by: Arvind Kumar <arvindkumar.acad@gmail.com>

* fix(mcp): keep a deferred oauth2-delegate server's own token when the JWT signer is on

Servers that defer to the v1 client, such as oauth2 with delegate_auth_to_upstream,
send their authentication_token in Authorization (or upstream_token_header), but the
signer guard only read the v2 spec and let the gateway JWT overwrite it. The guard
now falls back to v1's own header rule when to_server_spec returns None. BYOK keeps
its existing behavior.

* test(mcp): cover a SigV4 server's token leaving Authorization to the JWT signer

* fix(mcp): only let upstream_token_header claim Authorization for auth types v1 writes a key for

A SigV4 server with a stray authentication_token and upstream_token_header
set to Authorization lost the signer JWT, though v1 never sends that token.
The v1 rule now resolves the header v1 would write the key to, or none, before
applying the override.

* fix(mcp): keep the signer JWT on tools/call when the caller's auth header displaces the server key

A per-request MCP auth header replaces the server's authentication_token, so
the configured key is not what reaches Authorization. The tools/call guard now
only consults the server's configured key when the caller sent none, matching
the tools/list guard, so the upstream no longer ends up with no Authorization.

---------

Co-authored-by: Arvind Kumar <arvindkumar.acad@gmail.com>
This commit is contained in:
jesus-berri 2026-11-16 17:47:56 -08:00 • committed by GitHub
parent fe3e6bbb01
commit 43fc7d5cd3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 212 additions and 18 deletions

View file

@ -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,

View file

@ -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}