docs(mcp_zero_trust): add MCP zero trust auth guide#23918
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Greptile SummaryThis PR adds a new documentation page ( The guide covers the full feature surface — basic setup, IdP identity threading, required/optional claim enforcement, custom claim injection, AWS Bedrock AgentCore Gateway's two-token model, scope control, and debug tooling. The structure is clean and the examples are practical. Issues found:
Confidence Score: 4/5
|
| Filename | Overview |
|---|---|
| docs/my-website/docs/mcp_zero_trust.md | New use-case-driven guide for MCPJWTSigner; contains unused Tabs/TabItem imports, a debug-header example missing the aud claim despite telling users to check it, and a potentially misleading "least-privilege" scope list that grants mcp:tools/call on list-tools operations. |
| docs/my-website/static/img/mcp_zero_trust_gateway.png | Hero image for the new MCP zero trust guide; binary asset, no issues. |
Sequence Diagram
sequenceDiagram
participant Client
participant LiteLLM as LiteLLM Proxy
participant IdP as Corporate IdP
participant MCPServer as MCP Server
Client->>LiteLLM: Tool call request + Bearer token (IdP or API key)
LiteLLM->>IdP: Validate incoming token (JWKS / introspection)
IdP-->>LiteLLM: Token claims (sub, email, groups, ...)
Note over LiteLLM: MCPJWTSigner guardrail<br/>1. Check required_claims<br/>2. Build outbound JWT<br/> (add/set/remove claims)<br/>3. Sign RS256 JWT
LiteLLM->>MCPServer: Tool call + Authorization: Bearer <signed-JWT>
MCPServer->>LiteLLM: GET /.well-known/jwks.json
LiteLLM-->>MCPServer: JWKS (RSA public key)
MCPServer-->>MCPServer: Verify JWT signature, iss, aud, exp
MCPServer-->>LiteLLM: Tool result
LiteLLM-->>Client: Response
Last reviewed commit: "fix(docs): move hero..."
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| @@ -0,0 +1,294 @@ | |||
| import Tabs from '@theme/Tabs'; | |||
There was a problem hiding this comment.
mcp_zero_trust is not listed in docs/my-website/sidebars.js. Without this entry the page is only reachable via direct URL; it won't appear in the /mcp category alongside the other MCP guides.
Add it to the sidebar in sidebars.js:
{
type: "category",
label: "/mcp - Model Context Protocol",
items: [
"mcp",
"mcp_usage",
"mcp_openapi",
"mcp_oauth",
"mcp_aws_sigv4",
+ "mcp_zero_trust",
"mcp_public_internet",
"mcp_semantic_filter",
"mcp_control",
"mcp_cost",
"mcp_guardrail",
"mcp_troubleshoot",
]
},| - "mcp:tools/list" | ||
| - "mcp:admin" |
There was a problem hiding this comment.
debug_headers warning should be more prominent
The note about disabling debug_headers in production is easy to miss at the end of a paragraph. Because this header leaks signed claim metadata (including sub, iss, email, etc.) to any observer of the HTTP response, it deserves a dedicated admonition block, e.g.:
:::danger Production risk
`debug_headers: true` adds `x-litellm-mcp-debug` to every response. This header exposes JWT claim metadata (including `sub`, `email`, `iss`) to any party that can read HTTP responses. **Always disable this in production.**
:::
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; |
There was a problem hiding this comment.
Tabs and TabItem never referenced
Tabs and TabItem are imported at the top of the file, but neither component appears anywhere in the document. These are dead imports that can cause ESLint/MDX lint warnings and should be removed.
| import Tabs from '@theme/Tabs'; | |
| import TabItem from '@theme/TabItem'; |
(Remove both import lines entirely — the page uses no tab components.)
| x-litellm-mcp-debug: v=1; kid=a3f1b2c4d5e6f708; [email protected]; iss=https://my-litellm.example.com; exp=1712345678; scope=mcp:tools/call mcp:tools/get_weather:call | ||
| ``` | ||
|
|
||
| Check that `kid` matches what the MCP server fetched from JWKS, `iss`/`aud` match your server's expected values, and `exp` hasn't passed. Disable in production — the header leaks claim metadata. |
There was a problem hiding this comment.
aud absent from debug header example but referenced in verification guidance
Line 265 tells users to "Check that iss/aud match your server's expected values," yet the example x-litellm-mcp-debug header on line 262 does not include aud:
x-litellm-mcp-debug: v=1; kid=a3f1b2c4d5e6f708; [email protected]; iss=https://my-litellm.example.com; exp=1712345678; scope=mcp:tools/call mcp:tools/get_weather:call
If the implementation genuinely omits aud from the debug header, users won't be able to use debug_headers to diagnose audience mismatches — which is one of the most common JWT rejection causes. Either:
- Update the example to include
aud, e.g.aud=mcp-resource, or - Remove the reference to checking
audfrom the verification guidance on line 265, since the debug header won't expose it.
| By default LiteLLM generates least-privilege scopes per request: | ||
| - Tool call → `mcp:tools/call mcp:tools/{name}:call` | ||
| - List tools → `mcp:tools/call mcp:tools/list` |
There was a problem hiding this comment.
mcp:tools/call — likely a copy-paste error
The default scope table shows:
- Tool call → `mcp:tools/call mcp:tools/{name}:call`
- List tools → `mcp:tools/call mcp:tools/list`
The "list tools" scope includes mcp:tools/call, which is semantically meant for calling tools, not listing them. A least-privilege scope for listing would be only mcp:tools/list. Including the call scope on a list operation grants broader permissions than needed and contradicts the "least-privilege" claim made in the opening sentence of this section.
If the implementation genuinely issues mcp:tools/call for list operations, this warrants a clarifying note; otherwise it looks like a documentation error.
1 participant
Relevant issues
Companion docs for #23897 (MCPJWTSigner guardrail).
Pre-Submission checklist
Type
Changes
Adds
docs/my-website/docs/mcp_zero_trust.md— use-case-driven guide for the MCPJWTSigner guardrail:access_token_discovery_uri,end_user_claim_sources)required_claims,optional_claims)add_claims,set_claims,remove_claims)channel_token_audience,channel_token_ttl)allowed_scopes)debug_headers)Adds hero image (
docs/my-website/img/mcp_zero_trust_gateway.png).