fix(guardrails): don't add post_call output scan for MCP-only Presidio modes - #40571

TLDR

Problem this solves:

• MCP-only Presidio guardrails also scanned the final LLM answer
• Blocked MCP tool query repeated in the answer turned a 200 into a 400
• Tag-based mode objects were not recognized as MCP-only

How it solves it:

• Modes made only of pre_mcp_call / during_mcp_call / post_mcp_call default to presidio_filter_scope: input
• Works for a string, a list, and a tag-based mode (tags plus default)
• Explicit presidio_filter_scope: both or output still scans the answer

User Flow

Before: a developer asks the model to run an MCP tool with a phone number in the query, and the whole request fails even though only the tool call should be blocked

1. The proxy admin configures a Presidio guardrail with mode: pre_mcp_call and PHONE_NUMBER: BLOCK, plus one MCP server
2. The developer sends POST http://localhost:4000/v1/responses with the MCP tool and the input "search for exactly this text: call me at 415-555-2671, repeat the exact query in your answer"
3. The tool call is blocked as expected, and the model writes an answer that repeats the phone number
4. The response comes back as HTTP 400 Blocked entity detected: PHONE_NUMBER by Guardrail: pre-mcp-pii-check, so the developer never sees the answer or the blocked tool result

After: the same request returns the answer, with the blocked tool result inside it

1. The proxy admin configures the same guardrail and MCP server
2. The developer sends the same POST http://localhost:4000/v1/responses
3. The tool call is blocked as expected, and the model writes an answer that repeats the phone number
4. The response comes back as HTTP 200 with the assistant message and a tool_execution_results item reading Tool call blocked: PII entity 'PHONE_NUMBER' detected by guardrail 'pre-mcp-pii-check'

Relevant issues

Pylon #8386

Affected release

Linear ticket

Resolves LIT-7459

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• The handful of test files covering my change pass locally, e.g. uv run pytest tests/test_litellm/<your_test_file>.py -v. Leave the suites (make test-unit-*, make test-unit) to CI: it finishes in ~15 minutes where a laptop takes an hour or more
• My PR passes all required CI/CD checks (e.g., lint, schema.d.ts sync check, etc.)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Shared setup: Presidio analyzer and anonymizer containers (mcr.microsoft.com/presidio-analyzer, mcr.microsoft.com/presidio-anonymizer), a local MCP server exposing one web_search tool on http://127.0.0.1:27459/mcp, and the proxy started with litellm --config config.yaml --port 20459 --detailed_debug. Real OpenAI calls to gpt-4.1-mini

model_list:
  - model_name: gpt-4.1-mini
    litellm_params:
      model: openai/gpt-4.1-mini
      api_key: os.environ/OPENAI_API_KEY

mcp_servers:
  demo:
    url: http://127.0.0.1:27459/mcp
    transport: http

guardrails:
  - guardrail_name: pre-mcp-pii-check
    litellm_params:
      guardrail: presidio
      mode: pre_mcp_call
      presidio_analyzer_api_base: http://127.0.0.1:25459
      presidio_anonymizer_api_base: http://127.0.0.1:26459
      pii_entities_config:
        PHONE_NUMBER: BLOCK
        US_SSN: BLOCK
      default_on: true
      # case 2 only: presidio_filter_scope: both

general_settings:
  master_key: sk-1234

Request used in every run (req.json):

{
  "model": "gpt-4.1-mini",
  "input": "Use the web_search tool to search for exactly this text: \"call me at 415-555-2671\". Do not modify the query. In your final answer, always repeat the exact query text you searched for, verbatim, even if the tool failed.",
  "tools": [{"type": "mcp", "server_label": "litellm", "server_url": "litellm_proxy", "require_approval": "never"}]
}

Before (29a712b)

MCP-only mode, default scope

1. curl -s -i http://127.0.0.1:20459/v1/responses -H 'Authorization: Bearer sk-1234' -H 'content-type: application/json' -d @req.json
2. Observed:

HTTP/1.1 400 Bad Request
{"error":{"message":"Blocked entity detected: PHONE_NUMBER by Guardrail: pre-mcp-pii-check. This entity is not allowed to be used in this request.","type":"invalid_request_error","param":null,"code":"400"}}

3. Proxy log shows the tool call was blocked first, then the post-call scan of the assistant answer raised the 400:

async_post_call_success_hook response: ... text='I searched for the exact text: "call me at 415-555-2671" but the search was blocked ...'
... "result": "Tool call blocked: PII entity 'PHONE_NUMBER' detected by guardrail 'pre-mcp-pii-check'. ..."
LiteLLM Proxy:ERROR: common_request_processing.py - _handle_llm_api_exception(): Exception occured - Blocked entity detected: PHONE_NUMBER by Guardrail: pre-mcp-pii-check.

MCP-only mode with explicit presidio_filter_scope: both

1. Same curl against the config with presidio_filter_scope: both
2. Observed:

HTTP/1.1 400 Bad Request
{"error":{"message":"Blocked entity detected: PHONE_NUMBER by Guardrail: pre-mcp-pii-check. This entity is not allowed to be used in this request.","type":"invalid_request_error","param":null,"code":"400"}}

After (8a43fed)

MCP-only mode, default scope

1. curl -s -i http://127.0.0.1:20459/v1/responses -H 'Authorization: Bearer sk-1234' -H 'content-type: application/json' -d @req.json
2. Observed (trimmed to the relevant output items):

HTTP/1.1 200 OK
{
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "I attempted to search for the exact query \"call me at 415-555-2671\" but was unable to proceed because it contains a phone number, which is considered personal identifying information and is restricted by policy. The exact query text you asked me to search for is: \"call me at 415-555-2671\"."}]
    },
    {"type": "mcp_tools_fetched", "status": "completed", "role": "system", "content": [{"type": "output_text", "text": "[\n  \"name='demo-web_search' ..."}]},
    {
      "type": "tool_execution_results",
      "status": "completed",
      "role": "system",
      "content": [{"type": "output_text", "text": "[\n  {\n    \"tool_call_id\": \"call_llZNp30zpNrXohMNwVNrgFhV\",\n    \"result\": \"Tool call blocked: PII entity 'PHONE_NUMBER' detected by guardrail 'pre-mcp-pii-check'. Blocked entity detected: PHONE_NUMBER by Guardrail: pre-mcp-pii-check. This entity is not allowed to be used in this request.\",\n    \"name\": \"demo-web_search\"\n  }\n]"}]
    }
  ]
}

MCP-only mode with explicit presidio_filter_scope: both

1. Same curl against the config with presidio_filter_scope: both
2. Observed, unchanged from Before since the admin asked for output scanning:

HTTP/1.1 400 Bad Request
{"error":{"message":"Blocked entity detected: PHONE_NUMBER by Guardrail: pre-mcp-pii-check. This entity is not allowed to be used in this request.","type":"invalid_request_error","param":null,"code":"400"}}

Type

🐛 Bug Fix

Caveats (if any)

Medium

• Deployments relying on the implicit output scan of an MCP-only guardrail must now set presidio_filter_scope: both to keep it

Low

• Tag-based mode counts as MCP-only only when every tag value and the default are MCP hooks; a mix keeps the old both default
• An empty tag-based mode (no tags, no default) also keeps the old both default

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

Link to Devin session: https://app.devin.ai/sessions/f346adfada8f43468f6d29bcc05630bd
Open in Devin Desktop: https://app.devin.ai/desktop/session/f346adfada8f43468f6d29bcc05630bd?variant=devin
Requested by: @yassin-berriai