docs(mcp): scan tool descriptions on discovery and pin a server's tool list

[mateo-berri]

TLDR

Documents two new MCP gateway controls: tool descriptions and input schemas now run through the pre_mcp_call guardrails when a client discovers a server's tools, and admins can pin a server's tool list and descriptions so the gateway serves the pinned catalog and alerts on upstream drift

What changed

docs/mcp_guardrail.md gets a "Scanning Tool Descriptions on Discovery" section: which texts are scanned, what a block, a mask, and the mcp_tool_description_blocked alert look like, a config example, and the list_mcp_tools call type custom guardrails see

docs/mcp_control.md gets a "Pin a Server's Tool List" section: the POST and DELETE /v1/mcp/server/{server_id}/pin routes with example responses, the pinned_tools config mapping, the serving behavior, and the mcp_pinned_tools_changed drift alert

docs/mcp_config_reference.md links both sections and docs/proxy/alerting.md lists the two new alert types

Companion PR

The feature lands in BerriAI/litellm; this PR merges once that one does. BerriAI/litellm#43283

---

Note

Low Risk
Documentation-only changes with no runtime or security behavior in this repository.

Overview
Docs-only update for two MCP gateway security features (implementation in the companion litellm PR).

Discovery guardrail scanning (mcp_guardrail.md): Documents that pre_mcp_call guardrails now evaluate upstream tool descriptions and input-schema description fields during tools/list (including REST and LLM-driven discovery). Blocked tools are omitted from listings; masked text is served; mcp_tool_description_blocked alerts fire. Adds config/curl examples, custom-guardrail list_mcp_tools hook details, and a cross-link from OpenAPI description overrides.

Tool catalog pinning (mcp_control.md): Documents freezing tool names, descriptions, and input schemas via POST/DELETE /v1/mcp/server/{server_id}/pin or pinned_tools in config, client-visible behavior (403 for unpinned tools), and mcp_pinned_tools_changed drift alerts. Notes interaction with discovery guardrails, allowed_tools, and tool_name_to_description.

Cross-links: mcp_config_reference.md related-docs entries; new MCP Gateway Alerts rows in proxy/alerting.md.

^{Reviewed by Cursor Bugbot for commit 5eb874b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
litellm	Ready	Preview	Sep 26, 2026 8:25pm UTC

[mateo-berri]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 5eb874b. Configure here.}