diff --git a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py index 7eddf592262..df77297850b 100644 --- a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py +++ b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py @@ -7,6 +7,7 @@ This is a Proxy """ import asyncio +import copy import datetime import hashlib import json @@ -1873,6 +1874,56 @@ def _record_mcp_guardrail_evaluations( verbose_logger.warning("Failed to record MCP guardrail evaluation for logging: %s", e) +MCP_GUARDRAIL_BLOCKED_ARGUMENTS_PLACEHOLDER: Final[Mapping[str, str]] = MappingProxyType( + {"[redacted]": "blocked by guardrail"} +) +MCP_GUARDRAIL_MODIFIED_ARGUMENTS_PLACEHOLDER: Final[Mapping[str, str]] = MappingProxyType( + {"[redacted]": "modified by guardrail"} +) + + +def _replace_logged_mcp_tool_arguments( + litellm_logging_obj: "LiteLLMLoggingObj | None", + original_arguments: Mapping[str, object], + logged_arguments: Mapping[str, object], + mismatch_placeholder: Mapping[str, object], +) -> None: + """Point every spend-log copy of a tool call's inputs at ``logged_arguments``. + + ``mcp_tool_call_metadata`` and ``litellm_params["proxy_server_request"]`` are both filled + with the raw arguments before the ``pre_mcp_call`` guardrails run. A request body whose + ``arguments`` are not the tool's own (the ``/mcp/proxy`` virtual tool wraps them) gets + ``mismatch_placeholder`` instead of being rewritten in place. + """ + if litellm_logging_obj is None: + return + try: + model_call_details: Final = litellm_logging_obj.model_call_details + metadata: Final = model_call_details.get("mcp_tool_call_metadata") + if isinstance(metadata, dict) and "arguments" in metadata: + metadata["arguments"] = dict(logged_arguments) + litellm_params: Final = model_call_details.get("litellm_params") + proxy_server_request: Final = ( + cast(dict[str, object], litellm_params).get("proxy_server_request") # cast-ok: litellm_params is str-keyed + if isinstance(litellm_params, dict) + else None + ) + if not isinstance(proxy_server_request, dict): + return + request_record: Final = cast(dict[str, object], proxy_server_request) # cast-ok: rewritten in place, shared + body: Final = request_record.get("body") + if isinstance(body, Mapping) and "arguments" in body: + body_fields: Final = TypeAdapter(Mapping[str, object]).validate_python(body) + request_record["body"] = { + **body_fields, + "arguments": dict( + logged_arguments if body_fields["arguments"] == original_arguments else mismatch_placeholder + ), + } + except Exception as e: # noqa: BLE001 # runs on the block path; must not replace the guardrail's error + verbose_logger.error("Failed to scrub guardrailed MCP tool arguments from logging: %s", e) + + def _mcp_discovery_cache_ttl() -> float: raw: Final = os.environ.get("LITELLM_MCP_DISCOVERY_CACHE_TTL", "60") try: @@ -6208,13 +6259,23 @@ class MCPServerManager: synthetic_llm_data: Final = proxy_logging_obj.convert_mcp_to_llm_format(mcp_request_obj, pre_hook_kwargs) synthetic_llm_data["litellm_logging_obj"] = litellm_logging_obj + # Snapshot before the hooks run: a guardrail may rewrite ``arguments`` in place. + original_arguments: Final = copy.deepcopy(arguments) try: - # Use standard pre_call_hook - modified_data: Final = await proxy_logging_obj.pre_call_hook( - user_api_key_dict=checked_auth, - data=synthetic_llm_data, - call_type=CallTypes.call_mcp_tool.value, - ) + try: + modified_data: Final = await proxy_logging_obj.pre_call_hook( + user_api_key_dict=checked_auth, + data=synthetic_llm_data, + call_type=CallTypes.call_mcp_tool.value, + ) + except BaseException: + _replace_logged_mcp_tool_arguments( + litellm_logging_obj, + original_arguments, + MCP_GUARDRAIL_BLOCKED_ARGUMENTS_PLACEHOLDER, + MCP_GUARDRAIL_BLOCKED_ARGUMENTS_PLACEHOLDER, + ) + raise await proxy_logging_obj.enforce_mcp_server_rate_limits(checked_auth, server) if modified_data: # Convert response back to MCP format and apply modifications @@ -6225,6 +6286,14 @@ class MCPServerManager: hook_result["arguments"] = modified_kwargs["arguments"] if modified_kwargs.get("extra_headers"): hook_result["extra_headers"] = modified_kwargs["extra_headers"] + logged_arguments: Final[object] = hook_result.get("arguments", arguments) + if logged_arguments != original_arguments and isinstance(logged_arguments, Mapping): + _replace_logged_mcp_tool_arguments( + litellm_logging_obj, + original_arguments, + TypeAdapter(Mapping[str, object]).validate_python(logged_arguments), + MCP_GUARDRAIL_MODIFIED_ARGUMENTS_PLACEHOLDER, + ) except ( BlockedPiiEntityError, diff --git a/litellm/proxy/_experimental/mcp_server/operations.py b/litellm/proxy/_experimental/mcp_server/operations.py index 39e882fcab0..6708be5f2af 100644 --- a/litellm/proxy/_experimental/mcp_server/operations.py +++ b/litellm/proxy/_experimental/mcp_server/operations.py @@ -393,11 +393,10 @@ async def _log_virtual_mcp_tool_failure( request_logging_obj.post_call_failure_hook ) await failure_hook( - request_data={ - "name": name, - "arguments": arguments, - "litellm_logging_obj": failure_logging_obj, - }, + request_data=_failure_hook_request_data( + failure_logging_obj, + {"name": name, "arguments": arguments, "litellm_logging_obj": failure_logging_obj}, + ), original_exception=exc, user_api_key_dict=user_api_key_auth, route="/mcp/call_tool", @@ -2742,6 +2741,30 @@ def suppress_completed_success_logging(logging_obj: LiteLLMLoggingObj) -> None: logging_obj.mark_logging_complete(event_type="async_success") +def _failure_hook_request_data( + logging_obj: LiteLLMLoggingObj | None, request_data: Mapping[str, object] +) -> dict[str, object]: # mutable-ok: post_call_failure_hook callbacks write into request_data + """``request_data`` for ``post_call_failure_hook`` callbacks, minus credential fields. + + ``arguments`` is taken from the logger's recorded request body, which ``pre_call_tool_check`` + replaces once a ``pre_mcp_call`` guardrail has blocked or rewritten the tool inputs, so the + raw values the caller sent do not reach the callbacks. + """ + sanitized: Final = {key: value for key, value in request_data.items() if key not in _MCP_CREDENTIAL_REQUEST_FIELDS} + litellm_params: Final[object] = ( + logging_obj.model_call_details.get("litellm_params") if logging_obj is not None else None + ) + proxy_server_request: Final = _mapping_field(litellm_params, "proxy_server_request") + logged_arguments: Final = _mapping_field(_mapping_field(proxy_server_request, "body"), "arguments") + if "arguments" not in sanitized or logged_arguments is None: + return sanitized + return {**sanitized, "arguments": logged_arguments} + + +def _mapping_field(value: object, key: str) -> object: + return TypeAdapter(Mapping[str, object]).validate_python(value).get(key) if isinstance(value, Mapping) else None + + async def _fire_mcp_tool_call_logging( logging_obj: LiteLLMLoggingObj, result: CallToolResult, @@ -2797,11 +2820,8 @@ async def _fire_mcp_tool_call_logging( return result if proxy_logging_obj: - sanitized_request_data: Final = { - key: value for key, value in (request_data or {}).items() if key not in _MCP_CREDENTIAL_REQUEST_FIELDS - } await proxy_logging_obj.post_call_failure_hook( - request_data=sanitized_request_data, + request_data=_failure_hook_request_data(logging_obj, request_data or {}), original_exception=tool_error, user_api_key_dict=user_api_key_auth, route="/mcp/call_tool", @@ -2835,11 +2855,8 @@ async def fire_mcp_tool_call_failure_logging( if isinstance(exception, MCPUpstreamAuthError) or not proxy_logging_obj or user_api_key_auth is None: return - sanitized_request_data: Final = { - key: value for key, value in request_data.items() if key not in _MCP_CREDENTIAL_REQUEST_FIELDS - } await proxy_logging_obj.post_call_failure_hook( - request_data=sanitized_request_data, + request_data=_failure_hook_request_data(logging_obj, request_data), original_exception=exception, user_api_key_dict=user_api_key_auth, route="/mcp/call_tool", diff --git a/tests/unit/proxy/_experimental/mcp_server/test_mcp_block_recording.py b/tests/unit/proxy/_experimental/mcp_server/test_mcp_block_recording.py index 746130fb892..fd98e332a12 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_mcp_block_recording.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_mcp_block_recording.py @@ -45,6 +45,7 @@ class _RecordingLoggingObj: self._order = order self.failure_calls = 0 self.async_failure_calls = 0 + self.model_call_details: dict[str, object] = {} def failure_handler(self, *_args, **_kwargs) -> None: self.failure_calls += 1 diff --git a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py index 7315315a619..1fb6a195176 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py @@ -91,6 +91,7 @@ from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler import litellm from litellm.integrations.custom_guardrail import CustomGuardrail import litellm.llms as litellm_llms +from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj from litellm.proxy.utils import ProxyLogging from litellm.types.guardrails import GuardrailEventHooks from litellm.types.integrations.slack_alerting import AlertType @@ -21606,3 +21607,89 @@ class TestMCPUpstreamRateLimitRetry: assert exc_info.value.fault == ServerListFault(tag="upstream_error", status_code=429) assert list_tools_page.await_count == 2 + + +RAW_TOOL_ARGUMENTS: Final = {"text": "deploy with glpat-Xq7rT2mPz9Lk4vB8nWc3"} +MASKED_TOOL_ARGUMENTS: Final = {"text": "deploy with [MASKED]"} +BLOCKED_TOOL_ARGUMENTS: Final = {"[redacted]": "blocked by guardrail"} + + +class _CredentialGuardrail(CustomGuardrail): + def __init__(self, outcome: Literal["block", "mask", "pass"]) -> None: + super().__init__(guardrail_name="credential-guardrail", event_hook="pre_mcp_call", default_on=True) + self.outcome = outcome + + async def async_pre_call_hook(self, user_api_key_dict, cache, data, call_type): + if self.outcome == "block": + raise HTTPException(status_code=400, detail="credential detected") + if self.outcome == "mask": + return {**data, "modified_arguments": dict(MASKED_TOOL_ARGUMENTS)} + return data + + +def _tool_call_logger(body_arguments: dict[str, object]) -> LiteLLMLoggingObj: + logging_obj: Final = LiteLLMLoggingObj( + model="MCP: echo", + messages=[], + stream=False, + call_type="call_mcp_tool", + start_time=datetime(2026, 1, 1), + litellm_call_id="call-1", + function_id="fn-1", + ) + logging_obj.model_call_details["mcp_tool_call_metadata"] = {"name": "echo", "arguments": dict(RAW_TOOL_ARGUMENTS)} + logging_obj.model_call_details["litellm_params"] = { + "proxy_server_request": {"body": {"name": "echo", "arguments": body_arguments}} + } + return logging_obj + + +async def _run_guardrailed_tool_check( + monkeypatch: pytest.MonkeyPatch, outcome: Literal["block", "mask", "pass"], logging_obj: LiteLLMLoggingObj +) -> None: + monkeypatch.setattr(litellm, "callbacks", [_CredentialGuardrail(outcome)]) + call: Final = MCPServerManager().pre_call_tool_check( + name="echo", + arguments=dict(RAW_TOOL_ARGUMENTS), + server_name="echo", + user_api_key_auth=UserAPIKeyAuth(), + proxy_logging_obj=ProxyLogging(user_api_key_cache=DualCache()), + server=MCPServer(server_id="echo", name="echo", server_name="echo", transport=MCPTransport.http), + litellm_logging_obj=logging_obj, + ) + if outcome != "block": + await call + return + with pytest.raises(HTTPException): + await call + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("outcome", "logged"), + [("block", BLOCKED_TOOL_ARGUMENTS), ("mask", MASKED_TOOL_ARGUMENTS), ("pass", RAW_TOOL_ARGUMENTS)], +) +async def test_pre_call_tool_check_logs_only_the_arguments_the_guardrail_let_through(monkeypatch, outcome, logged): + logging_obj: Final = _tool_call_logger(dict(RAW_TOOL_ARGUMENTS)) + + await _run_guardrailed_tool_check(monkeypatch, outcome, logging_obj) + + details: Final = logging_obj.model_call_details + assert details["mcp_tool_call_metadata"]["arguments"] == logged + assert details["litellm_params"]["proxy_server_request"]["body"] == {"name": "echo", "arguments": logged} + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("outcome", "logged_body_arguments"), + [("block", BLOCKED_TOOL_ARGUMENTS), ("mask", {"[redacted]": "modified by guardrail"})], +) +async def test_pre_call_tool_check_replaces_a_wrapping_request_body_with_a_placeholder( + monkeypatch, outcome, logged_body_arguments +): + logging_obj: Final = _tool_call_logger({"tool_id": "echo", "arguments": dict(RAW_TOOL_ARGUMENTS)}) + + await _run_guardrailed_tool_check(monkeypatch, outcome, logging_obj) + + body: Final = logging_obj.model_call_details["litellm_params"]["proxy_server_request"]["body"] + assert body["arguments"] == logged_body_arguments diff --git a/tests/unit/proxy/_experimental/mcp_server/test_operations.py b/tests/unit/proxy/_experimental/mcp_server/test_operations.py index 6f7437c90dc..80768c5ab74 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_operations.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_operations.py @@ -4,6 +4,7 @@ from typing import Final, Literal from unittest.mock import AsyncMock, patch import pytest +from fastapi import HTTPException from mcp.server.context import ServerRequestContext from mcp.types import GetPromptRequest, GetPromptRequestParams, GetPromptResult from mcp.types import Tool as MCPTool @@ -2035,3 +2036,48 @@ async def test_discovery_optional_probes_use_remaining_listing_budget(delay, mon else: assert entered.is_set() assert cleaned.is_set() + + +class _FailureHookArguments(CustomLogger): + def __init__(self) -> None: + super().__init__() + self.seen: list[object] = [] + + async def async_post_call_failure_hook(self, request_data, original_exception, user_api_key_dict, traceback_str=None): + self.seen.append(request_data.get("arguments")) + + +@pytest.mark.asyncio +async def test_failure_hooks_see_the_guardrail_logged_arguments_not_the_raw_ones(monkeypatch): + from datetime import datetime + + from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj + from litellm.proxy import proxy_server + + blocked: Final = {"[redacted]": "blocked by guardrail"} + raw: Final = {"text": "deploy with glpat-Xq7rT2mPz9Lk4vB8nWc3"} + callback: Final = _FailureHookArguments() + monkeypatch.setattr(litellm, "callbacks", [callback]) + monkeypatch.setattr(proxy_server, "proxy_logging_obj", ProxyLogging(user_api_key_cache=DualCache())) + logging_obj: Final = LiteLLMLoggingObj( + model="MCP: echo", + messages=[], + stream=False, + call_type="call_mcp_tool", + start_time=datetime(2026, 1, 1), + litellm_call_id="call-1", + function_id="fn-1", + ) + logging_obj.model_call_details["litellm_params"] = { + "proxy_server_request": {"body": {"name": "echo", "arguments": blocked}} + } + + await operations.fire_mcp_tool_call_failure_logging( + logging_obj, + HTTPException(status_code=400, detail="credential detected"), + datetime(2026, 1, 1), + UserAPIKeyAuth(), + {"name": "echo", "arguments": raw, "litellm_logging_obj": logging_obj}, + ) + + assert callback.seen == [blocked]