diff --git a/litellm/integrations/custom_guardrail.py b/litellm/integrations/custom_guardrail.py index a9fb5c29bad..99bfa9ab2e4 100644 --- a/litellm/integrations/custom_guardrail.py +++ b/litellm/integrations/custom_guardrail.py @@ -65,6 +65,10 @@ from litellm.exceptions import ( GUARDRAIL_SESSIONS_TARGET: Final = "guardrail_sessions" +MCP_SERVER_GUARDRAILS_KEY: Final = "mcp_server_guardrails" + +_MCP_SERVER_SCOPED_HOOKS: Final = frozenset({GuardrailEventHooks.pre_mcp_call, GuardrailEventHooks.post_mcp_call}) + # Per-process secret tagging each recorded marker. The deployment hook only # honors markers carrying this token, so a caller cannot forge the metadata # field to suppress a guardrail on the direct-SDK path that never reaches the @@ -1199,6 +1203,9 @@ class CustomGuardrail(CustomLogger): if self._suppressed_by_auto_router_compression(): return False + if self._attached_to_mcp_server(cast(object, data), event_type): # cast-ok: untyped data param + return self._event_hook_is_event_type(event_type) + requested_guardrails: Final = self.get_guardrail_from_metadata(data) disable_global_guardrail: Final = self.get_disable_global_guardrail(data) opted_out_global_guardrails: Final = self.get_opted_out_global_guardrails_from_metadata(data) @@ -1262,6 +1269,12 @@ class CustomGuardrail(CustomLogger): return mode_tag_result and self.stream_scope_allows(cast(object, data), event_type) # cast-ok: data return self.stream_scope_allows(cast(object, data), event_type) # cast-ok: data param + def _attached_to_mcp_server(self, data: object, event_type: GuardrailEventHooks) -> bool: + if event_type not in _MCP_SERVER_SCOPED_HOOKS or not isinstance(data, Mapping): + return False + server_guardrails: Final = cast(Mapping[str, object], data).get(MCP_SERVER_GUARDRAILS_KEY) # cast-ok: data + return isinstance(server_guardrails, list) and self.guardrail_name in server_guardrails + def _event_hook_is_event_type(self, event_type: GuardrailEventHooks) -> bool: """ Returns True if the event_hook is the same as the event_type diff --git a/litellm/proxy/mcp_server/mcp_server_manager.py b/litellm/proxy/mcp_server/mcp_server_manager.py index c772e2e9d09..f81bf5e068a 100644 --- a/litellm/proxy/mcp_server/mcp_server_manager.py +++ b/litellm/proxy/mcp_server/mcp_server_manager.py @@ -73,6 +73,7 @@ from litellm.constants import ( MCP_UPSTREAM_SESSION_SHUTDOWN_TIMEOUT_SECONDS, ) from litellm.exceptions import BlockedPiiEntityError, GuardrailRaisedException +from litellm.integrations.custom_guardrail import MCP_SERVER_GUARDRAILS_KEY from litellm.litellm_core_utils.url_utils import SSRFError, async_safe_get from litellm.llms.custom_httpx.http_handler import get_async_httpx_client from litellm.mcp_client.client import ( @@ -434,6 +435,7 @@ class MCPServerConfig(TypedDict, total=False): allowed_tools: _StringList disallowed_tools: _StringList allowed_params: _ToolParamMap + guardrails: _StringList access_groups: _StringList static_headers: _StringMap env_vars: _EnvVarList @@ -2817,6 +2819,7 @@ class MCPServerManager: disallowed_tools=server_config.get("disallowed_tools", None), allowed_params=server_config.get("allowed_params", None), pinned_tools=server_config.get("pinned_tools", None), + guardrails=server_config.get("guardrails", None), access_groups=server_config.get("access_groups", None), static_headers=server_config.get("static_headers", None), env_vars=server_config.get("env_vars", None), @@ -6293,6 +6296,7 @@ class MCPServerManager: and proxy_logging_obj.has_pre_call_guardrails( TypeAdapter(Mapping[str, object]).validate_python(initial_data.get("metadata") or {}), event_type=GuardrailEventHooks.pre_mcp_call, + server_guardrails=server.guardrails or (), ) else tool ) @@ -6311,6 +6315,7 @@ class MCPServerManager: else {} ), "litellm_logging_obj": litellm_logging_obj, + MCP_SERVER_GUARDRAILS_KEY: list(server.guardrails or ()), } try: diff --git a/litellm/proxy/mcp_server/operations.py b/litellm/proxy/mcp_server/operations.py index d486a69ef1a..1834da61867 100644 --- a/litellm/proxy/mcp_server/operations.py +++ b/litellm/proxy/mcp_server/operations.py @@ -55,6 +55,7 @@ from litellm.constants import ( MAXIMUM_TRACEBACK_LINES_TO_LOG, MCP_TOOL_LISTING_TIMEOUT, ) +from litellm.integrations.custom_guardrail import MCP_SERVER_GUARDRAILS_KEY from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj from litellm.proxy._types import ( UserAPIKeyAuth, @@ -2447,6 +2448,7 @@ async def _execute_mcp_tool( original_auth=user_api_key_auth, guardrail_auth=effective_guardrail_auth, request_data=kwargs, + server_guardrails=tuple(mcp_server.guardrails or ()), ), wire_compat=wire_compat, input_responses=input_responses, @@ -2545,6 +2547,7 @@ async def _execute_mcp_tool( original_auth=user_api_key_auth, guardrail_auth=effective_guardrail_auth, request_data=kwargs, + server_guardrails=tuple(mcp_server.guardrails or ()) if mcp_server is not None else (), ) @@ -2554,6 +2557,7 @@ def _guarded_progress_callback( original_auth: UserAPIKeyAuth | None, guardrail_auth: UserAPIKeyAuth | None, request_data: Mapping[str, object], + server_guardrails: tuple[str, ...] = (), ) -> ProgressCallback | None: if callback is None: return None @@ -2569,6 +2573,7 @@ def _guarded_progress_callback( original_auth=original_auth, guardrail_auth=guardrail_auth, request_data=request_data, + server_guardrails=server_guardrails, ) filtered: Final = TextContent.model_validate(checked.content[0]).text except Exception: # noqa: BLE001 # any guardrail failure must withhold unverified progress text @@ -2586,6 +2591,7 @@ async def _run_post_mcp_call_guardrails( original_auth: UserAPIKeyAuth | None, guardrail_auth: UserAPIKeyAuth | None, request_data: Mapping[str, object], + server_guardrails: tuple[str, ...] = (), ) -> CallToolResult: """Run ``post_mcp_call`` guardrails over an executed tool result. @@ -2604,6 +2610,7 @@ async def _run_post_mcp_call_guardrails( request_data_for_hook: Final = ( litellm_logging_obj.model_call_details if litellm_logging_obj is not None else dict(request_data) ) + request_data_for_hook[MCP_SERVER_GUARDRAILS_KEY] = list(server_guardrails) return await proxy_logging_obj.post_mcp_call_hook( response=result, request_data=request_data_for_hook, @@ -2674,6 +2681,7 @@ async def _run_post_mcp_call_guardrails( **resolved_auth_metadata, "guardrails": list(merged_guardrails), }, + MCP_SERVER_GUARDRAILS_KEY: list(server_guardrails), } return await proxy_logging_obj.post_mcp_call_hook( response=result, diff --git a/litellm/proxy/utils.py b/litellm/proxy/utils.py index ddaa8d2e69d..cf983e67305 100644 --- a/litellm/proxy/utils.py +++ b/litellm/proxy/utils.py @@ -145,6 +145,7 @@ from litellm.exceptions import ( SensitiveDataRouteException, ) from litellm.integrations.custom_guardrail import ( + MCP_SERVER_GUARDRAILS_KEY, CustomGuardrail, ModifyResponseException, ) @@ -2878,6 +2879,7 @@ class ProxyLogging: self, request_metadata: Mapping[str, object], event_type: GuardrailEventHooks = GuardrailEventHooks.pre_call, + server_guardrails: Sequence[str] = (), ) -> bool: """ Whether anything configured would inspect the content of a request carrying this metadata. @@ -2895,7 +2897,7 @@ class ProxyLogging: caps: Final = ProxyLogging.callback_capabilities() if caps.has_content_enforcer: return True - probe: Final = {"metadata": dict(request_metadata)} + probe: Final = {"metadata": dict(request_metadata), MCP_SERVER_GUARDRAILS_KEY: list(server_guardrails)} return any( isinstance(callback, CustomGuardrail) and callback.should_run_guardrail(data=probe, event_type=event_type) for callback in caps.resolved_callbacks diff --git a/litellm/types/mcp_server/mcp_server_manager.py b/litellm/types/mcp_server/mcp_server_manager.py index 0d39b0a0616..d49bc16d17a 100644 --- a/litellm/types/mcp_server/mcp_server_manager.py +++ b/litellm/types/mcp_server/mcp_server_manager.py @@ -112,6 +112,7 @@ class MCPServer(LiteLLMBaseModel): tool_name_to_display_name: dict[str, str] | None = None tool_name_to_description: dict[str, str] | None = None pinned_tools: dict[str, PinnedMCPTool] | None = None + guardrails: list[str] | None = None allowed_params: dict[str, list[str]] | None = None # map of tool names to allowed parameter lists static_headers: dict[str, str] | None = None # static headers to forward to the MCP server # Admin-configured env vars. Each entry is {name, value, scope, description}. diff --git a/tests/unit/proxy/mcp_server/test_mcp_server_guardrails.py b/tests/unit/proxy/mcp_server/test_mcp_server_guardrails.py new file mode 100644 index 00000000000..35d4d0d41e9 --- /dev/null +++ b/tests/unit/proxy/mcp_server/test_mcp_server_guardrails.py @@ -0,0 +1,139 @@ +"""Per-MCP-server ``guardrails``: a server's listed guardrails run for its tool calls only.""" + +from typing import Final, cast +from unittest.mock import AsyncMock, MagicMock, patch + +import pytest +from mcp.types import CallToolResult, TextContent + +from litellm.integrations.custom_guardrail import MCP_SERVER_GUARDRAILS_KEY, CustomGuardrail +from litellm.proxy.mcp_server import operations +from litellm.proxy.mcp_server.mcp_server_manager import MCPServerManager +from litellm.proxy.utils import ProxyLogging +from litellm.types.guardrails import GuardrailEventHooks +from litellm.types.mcp import MCPAuth, MCPTransport +from litellm.types.mcp_server.mcp_server_manager import MCPServer + +SCOPED: Final = "scoped-guardrail" + + +def _guardrail(mode: GuardrailEventHooks, default_on: bool = False) -> CustomGuardrail: + return CustomGuardrail(guardrail_name=SCOPED, event_hook=mode, default_on=default_on) + + +def _server(guardrails: list[str] | None) -> MCPServer: + return MCPServer( + server_id="tickets-id", + name="tickets", + server_name="tickets", + url="https://example.com/mcp", + transport=MCPTransport.http, + auth_type=MCPAuth.none, + guardrails=guardrails, + ) + + +@pytest.mark.parametrize("hook", [GuardrailEventHooks.pre_mcp_call, GuardrailEventHooks.post_mcp_call]) +def test_listed_guardrail_runs_for_its_server_without_default_on(hook: GuardrailEventHooks) -> None: + assert _guardrail(hook).should_run_guardrail({MCP_SERVER_GUARDRAILS_KEY: [SCOPED]}, hook) is True + + +@pytest.mark.parametrize("server_guardrails", [[], ["other"]]) +def test_unlisted_guardrail_does_not_run_on_another_server(server_guardrails: list[str]) -> None: + guardrail: Final = _guardrail(GuardrailEventHooks.pre_mcp_call) + data: Final = {MCP_SERVER_GUARDRAILS_KEY: server_guardrails} + assert guardrail.should_run_guardrail(data, GuardrailEventHooks.pre_mcp_call) is False + + +def test_listed_guardrail_still_honours_its_mode() -> None: + guardrail: Final = _guardrail(GuardrailEventHooks.post_mcp_call) + data: Final = {MCP_SERVER_GUARDRAILS_KEY: [SCOPED]} + assert guardrail.should_run_guardrail(data, GuardrailEventHooks.pre_mcp_call) is False + + +def test_server_list_is_ignored_outside_mcp_events() -> None: + guardrail: Final = CustomGuardrail(guardrail_name=SCOPED, event_hook=GuardrailEventHooks.pre_call) + data: Final = {MCP_SERVER_GUARDRAILS_KEY: [SCOPED]} + assert guardrail.should_run_guardrail(data, GuardrailEventHooks.pre_call) is False + + +def test_server_listing_overrides_key_opt_out() -> None: + guardrail: Final = _guardrail(GuardrailEventHooks.pre_mcp_call, default_on=True) + data: Final = {MCP_SERVER_GUARDRAILS_KEY: [SCOPED], "metadata": {"disable_global_guardrail": True}} + assert guardrail.should_run_guardrail(data, GuardrailEventHooks.pre_mcp_call) is True + + +@pytest.mark.asyncio +async def test_config_guardrails_are_loaded_onto_the_server( + config_only_mcp_manager_factory: type[MCPServerManager], +) -> None: + manager: Final = config_only_mcp_manager_factory() + await manager.load_servers_from_config( + {"tickets": {"url": "https://example.com/mcp", "transport": "http", "guardrails": [SCOPED]}} + ) + servers: Final = [s for s in manager.config_mcp_servers.values() if s.name == "tickets"] + assert [s.guardrails for s in servers] == [[SCOPED]] + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("listed", "expected"), [([SCOPED], [SCOPED]), (None, [])]) +async def test_pre_call_tool_check_passes_server_guardrails(listed: list[str] | None, expected: list[str]) -> None: + manager: Final = MCPServerManager() + proxy_logging: Final = MagicMock(spec=ProxyLogging) + proxy_logging.create_mcp_request_object_from_kwargs = MagicMock(return_value=MagicMock()) + proxy_logging.convert_mcp_to_llm_format = MagicMock(return_value={"model": "fake"}) + seen_data: Final[list[dict[str, object]]] = [] + seen_server_guardrails: Final[list[object]] = [] + + def has_pre_call_guardrails(*_args: object, **kwargs: object) -> bool: + seen_server_guardrails.append(kwargs["server_guardrails"]) + return False + + async def pre_call_hook(**kwargs: object) -> None: + seen_data.append(cast(dict[str, object], kwargs["data"])) + + proxy_logging.has_pre_call_guardrails = has_pre_call_guardrails + proxy_logging.pre_call_hook = pre_call_hook + proxy_logging.enforce_mcp_server_rate_limits = AsyncMock() + + with ( + patch.object(manager, "check_allowed_or_banned_tools", return_value=True), + patch.object(manager, "check_tool_permission_for_key_team", new_callable=AsyncMock), + patch.object(manager, "validate_allowed_params"), + ): + await manager.pre_call_tool_check( + name="get_ticket", + arguments={}, + server_name="tickets", + user_api_key_auth=None, + proxy_logging_obj=proxy_logging, + server=_server(listed), + ) + + assert [d[MCP_SERVER_GUARDRAILS_KEY] for d in seen_data] == [expected] + assert seen_server_guardrails == [listed or ()] + + +@pytest.mark.asyncio +async def test_post_call_guardrails_receive_server_guardrails() -> None: + result: Final = CallToolResult(content=[TextContent(type="text", text="ok")]) + proxy_logging: Final = MagicMock(spec=ProxyLogging) + seen_request_data: Final[list[dict[str, object]]] = [] + + async def post_mcp_call_hook(**kwargs: object) -> CallToolResult: + seen_request_data.append(cast(dict[str, object], kwargs["request_data"])) + return result + + proxy_logging.post_mcp_call_hook = post_mcp_call_hook + + with patch("litellm.proxy.proxy_server.proxy_logging_obj", proxy_logging): + await operations._run_post_mcp_call_guardrails( # pyright: ignore[reportPrivateUsage] + result=result, + litellm_logging_obj=None, + original_auth=None, + guardrail_auth=None, + request_data={MCP_SERVER_GUARDRAILS_KEY: ["forged"]}, + server_guardrails=(SCOPED,), + ) + + assert [d[MCP_SERVER_GUARDRAILS_KEY] for d in seen_request_data] == [[SCOPED]] diff --git a/tests/unit/proxy/mcp_server/test_mcp_server_tool_calls_and_headers.py b/tests/unit/proxy/mcp_server/test_mcp_server_tool_calls_and_headers.py index 621a7b65005..2dcb2b10f76 100644 --- a/tests/unit/proxy/mcp_server/test_mcp_server_tool_calls_and_headers.py +++ b/tests/unit/proxy/mcp_server/test_mcp_server_tool_calls_and_headers.py @@ -33,6 +33,7 @@ from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, LATEST_HANDSHAKE_VERS from pydantic import JsonValue, TypeAdapter from starlette.types import Message, Receive, Scope, Send +from litellm.integrations.custom_guardrail import MCP_SERVER_GUARDRAILS_KEY from litellm.proxy._types import ( LiteLLM_MCPServerTable, MCPTransport, @@ -11089,6 +11090,35 @@ class TestOboPreflightScopedToAllowedServers: ) +@pytest.mark.asyncio +@pytest.mark.parametrize(("listed", "expected"), [(["scoped-guardrail"], ["scoped-guardrail"]), (None, [])]) +async def test_call_mcp_tool_hands_server_guardrails_to_post_mcp_call_hook(listed, expected): + from litellm.proxy.mcp_server.server import call_mcp_tool + from litellm.types.mcp_server.mcp_server_manager import MCPServer + + server = MCPServer( + server_id="tickets-id", + name="tickets", + alias="tickets", + server_name="tickets", + url="https://example.com/mcp", + transport=MCPTransport.http, + mcp_info={"server_name": "tickets"}, + guardrails=listed, + ) + proxy_logging_mock = _mock_mcp_proxy_logging() + + with _managed_tool_returning(server, _call_tool_result(False, "ok"), proxy_logging_mock): + await call_mcp_tool( + name="tickets-get_ticket", + arguments={}, + user_api_key_auth=UserAPIKeyAuth(api_key="test-key", user_id="test-user"), + litellm_logging_obj=_mock_mcp_logging_obj(), + ) + + assert proxy_logging_mock.post_mcp_call_hook.await_args.kwargs["request_data"][MCP_SERVER_GUARDRAILS_KEY] == expected + + @pytest.mark.asyncio async def test_post_mcp_call_guardrails_return_the_rewritten_result(): """The result a post_mcp_call guardrail rewrote must be what the caller sends back.""" @@ -11147,7 +11177,10 @@ async def test_post_mcp_call_guardrails_run_without_a_logging_object(): assert returned is masked_result proxy_logging_mock.post_mcp_call_hook.assert_awaited_once() - assert proxy_logging_mock.post_mcp_call_hook.await_args.kwargs["request_data"] == {"name": "fetch_record"} + assert proxy_logging_mock.post_mcp_call_hook.await_args.kwargs["request_data"] == { + "name": "fetch_record", + MCP_SERVER_GUARDRAILS_KEY: [], + } @pytest.mark.asyncio