This commit is contained in:
Joshua Hoblitt 2026-10-30 13:45:51 -04:00 • committed by GitHub
commit 05b84ec0c3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 203 additions and 2 deletions

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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