feat(guardrails): MCPJWTSigner - built-in guardrail for zero trust MCP auth

docs/my-website/docs/mcp_zero_trust.md

@@ -0,0 +1,99 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# MCP Zero Trust Auth (JWT Signer)
+
+The `MCPJWTSigner` guardrail signs every outbound MCP tool call with a LiteLLM-issued RS256 JWT. MCP servers validate tokens against LiteLLM's JWKS endpoint instead of trusting each upstream IdP directly.
+
+## Architecture
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant LiteLLM
+    participant JWKS as LiteLLM JWKS<br/>/.well-known/jwks.json
+    participant MCP as MCP Server
+
+    Client->>LiteLLM: tool call (Bearer API key / JWT)
+    Note over LiteLLM: MCPJWTSigner.async_pre_call_hook()<br/>builds RS256 JWT:<br/>sub=user_id, act=team_id,<br/>scope=mcp:tools/{name}:call
+
+    LiteLLM->>MCP: call_tool(args)<br/>Authorization: Bearer <litellm-jwt>
+    MCP->>JWKS: GET /.well-known/jwks.json
+    JWKS-->>MCP: RSA public key (JWKS)
+    MCP->>MCP: verify JWT signature + claims
+    MCP-->>LiteLLM: tool result
+    LiteLLM-->>Client: response
+```
+
+### OIDC Discovery
+
+LiteLLM publishes standard OIDC discovery so MCP servers can find the signing key automatically:
+
+```
+GET /.well-known/openid-configuration
+→ { "jwks_uri": "https://<your-litellm>/.well-known/jwks.json", ... }
+
+GET /.well-known/jwks.json
+→ { "keys": [{ "kty": "RSA", "alg": "RS256", "kid": "...", "n": "...", "e": "..." }] }
+```
+
+## Setup
+
+### 1. Enable in `config.yaml`
+
+```yaml title="config.yaml"
+guardrails:
+  - guardrail_name: "mcp-jwt-signer"
+    litellm_params:
+      guardrail: mcp_jwt_signer
+      mode: pre_mcp_call
+      default_on: true
+      issuer: "https://my-litellm.example.com"  # optional — defaults to request base URL
+      audience: "mcp"                            # optional — default: "mcp"
+      ttl_seconds: 300                           # optional — default: 300
+```
+
+### 2. (Optional) Bring your own RSA key
+
+If unset, LiteLLM auto-generates an RSA-2048 keypair at startup (lost on restart).
+
+```bash
+# PEM string
+export MCP_JWT_SIGNING_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
+
+# Or point to a file
+export MCP_JWT_SIGNING_KEY="file:///secrets/mcp-signing-key.pem"
+```
+
+### 3. Configure your MCP server to verify tokens
+
+Point your MCP server at LiteLLM's OIDC discovery endpoint:
+
+```
+https://<your-litellm>/.well-known/openid-configuration
+```
+
+Most JWT middleware (e.g. `python-jose`, `jsonwebtoken`, AWS Lambda authorizers) supports OIDC auto-discovery.
+
+## JWT Claims
+
+| Claim | Value | RFC |
+|-------|-------|-----|
+| `iss` | LiteLLM issuer URL | RFC 7519 |
+| `aud` | configured `audience` | RFC 7519 |
+| `sub` | `user_api_key_dict.user_id` | RFC 8693 |
+| `act.sub` | `team_id` → `org_id` → `"litellm-proxy"` | RFC 8693 delegation |
+| `email` | `user_api_key_dict.user_email` (if set) | — |
+| `scope` | `mcp:tools/call mcp:tools/list mcp:tools/{name}:call` | — |
+| `iat`, `exp`, `nbf` | standard timing | RFC 7519 |
+
+## Limitations
+
+- **OpenAPI-backed MCP servers** (`spec_path` set) do not support hook header injection. Calls to these servers will fail with a 500 if `MCPJWTSigner` is active with `default_on: true`. Use SSE/HTTP transport MCP servers instead.
+- The keypair is **in-memory by default** — rotated on every restart unless `MCP_JWT_SIGNING_KEY` is set. MCP servers should re-fetch JWKS on verification failure (short JWKS cache TTL recommended).
+
+## Related
+
+- [MCP Guardrails](./mcp_guardrail) — PII masking and blocking for MCP calls
+- [MCP OAuth](./mcp_oauth) — upstream OAuth2 for MCP server access
+- [MCP AWS SigV4](./mcp_aws_sigv4) — AWS-signed requests to MCP servers

docs/my-website/sidebars.js

@@ -636,6 +636,7 @@ const sidebars = {
             "mcp_control",
             "mcp_cost",
             "mcp_guardrail",
+            "mcp_zero_trust",
             "mcp_troubleshoot",
           ]
         },

litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py

@@ -677,7 +677,57 @@ async def oauth_authorization_server_mcp(
 # Alias for standard OpenID discovery
 @router.get("/.well-known/openid-configuration")
 async def openid_configuration(request: Request):
-    return await oauth_authorization_server_mcp(request)
+    response = await oauth_authorization_server_mcp(request)
+
+    # If MCPJWTSigner is active, augment the discovery doc with JWKS fields so
+    # MCP servers and gateways (e.g. AWS Bedrock AgentCore Gateway) can resolve
+    # the signing keys and verify liteLLM-issued tokens.
+    try:
+        from litellm.proxy.guardrails.guardrail_hooks.mcp_jwt_signer.mcp_jwt_signer import (
+            get_mcp_jwt_signer,
+        )
+
+        signer = get_mcp_jwt_signer()
+        if signer is not None:
+            request_base_url = get_request_base_url(request)
+            if isinstance(response, dict):
+                response["jwks_uri"] = f"{request_base_url}/.well-known/jwks.json"
+                response["id_token_signing_alg_values_supported"] = ["RS256"]
+    except ImportError:
+        pass
+
+    return response
+
+
+@router.get("/.well-known/jwks.json")
+async def jwks_json(request: Request):
+    """
+    JSON Web Key Set endpoint.
+
+    Returns the RSA public key used by MCPJWTSigner to sign outbound MCP tokens.
+    MCP servers and gateways use this endpoint to verify liteLLM-issued JWTs.
+
+    Returns an empty key set if MCPJWTSigner is not configured.
+    """
+    try:
+        from litellm.proxy.guardrails.guardrail_hooks.mcp_jwt_signer.mcp_jwt_signer import (
+            get_mcp_jwt_signer,
+        )
+
+        signer = get_mcp_jwt_signer()
+        if signer is not None:
+            return JSONResponse(
+                content=signer.get_jwks(),
+                headers={"Cache-Control": f"public, max-age={signer.jwks_max_age}"},
+            )
+    except ImportError:
+        pass
+
+    # No signer active — return empty key set; short cache so activation is picked up quickly.
+    return JSONResponse(
+        content={"keys": []},
+        headers={"Cache-Control": "public, max-age=60"},
+    )
 
 
 # Additional legacy pattern support

litellm/proxy/_experimental/mcp_server/mcp_server_manager.py

@@ -1908,7 +1908,14 @@ async def pre_call_tool_check(
         user_api_key_auth: Optional[UserAPIKeyAuth],
         proxy_logging_obj: ProxyLogging,
         server: MCPServer,
-    ):
+    ) -> Dict[str, Any]:
+        """
+        Run pre-call checks and guardrail hooks for an MCP tool call.
+
+        Returns a dict that may contain:
+        - "arguments": hook-modified tool arguments (only if changed)
+        - "extra_headers": headers injected by pre_mcp_call guardrail hooks
+        """
         ## check if the tool is allowed or banned for the given server
         if not self.check_allowed_or_banned_tools(name, server):
             raise HTTPException(
@@ -1969,6 +1976,7 @@ async def pre_call_tool_check(
             mcp_request_obj, pre_hook_kwargs
         )
 
+        hook_result: Dict[str, Any] = {}
         try:
             # Use standard pre_call_hook
             modified_data = await proxy_logging_obj.pre_call_hook(
@@ -1984,7 +1992,9 @@ async def pre_call_tool_check(
                     )
                 )
                 if modified_kwargs.get("arguments") != arguments:
-                    arguments = modified_kwargs["arguments"]
+                    hook_result["arguments"] = modified_kwargs["arguments"]
+                if modified_kwargs.get("extra_headers"):
+                    hook_result["extra_headers"] = modified_kwargs["extra_headers"]
 
         except (
             BlockedPiiEntityError,
@@ -1995,6 +2005,8 @@ async def pre_call_tool_check(
             verbose_logger.error(f"Guardrail blocked MCP tool call pre call: {str(e)}")
             raise e
 
+        return hook_result
+
     def _create_during_hook_task(
         self,
         name: str,
@@ -2047,6 +2059,7 @@ async def _call_regular_mcp_tool(
         raw_headers: Optional[Dict[str, str]],
         proxy_logging_obj: Optional[ProxyLogging],
         host_progress_callback: Optional[Callable] = None,
+        hook_extra_headers: Optional[Dict[str, str]] = None,
     ) -> CallToolResult:
         """
         Call a regular MCP tool using the MCP client.
@@ -2061,6 +2074,9 @@ async def _call_regular_mcp_tool(
             oauth2_headers: Optional OAuth2 headers
             raw_headers: Optional raw headers from the request
             proxy_logging_obj: Optional ProxyLogging object for hook integration
+            host_progress_callback: Optional callback for progress updates
+            hook_extra_headers: Optional headers injected by pre_mcp_call guardrail
+                hooks. Merged last (highest priority) into outbound request headers.
 
         Returns:
             CallToolResult from the MCP server
@@ -2116,6 +2132,11 @@ async def _call_regular_mcp_tool(
                 extra_headers = {}
             extra_headers.update(mcp_server.static_headers)
 
+        if hook_extra_headers:
+            if extra_headers is None:
+                extra_headers = {}
+            extra_headers.update(hook_extra_headers)
+
         stdio_env = self._build_stdio_env(mcp_server, raw_headers)
 
         client = await self._create_mcp_client(
@@ -2201,15 +2222,18 @@ async def call_tool(
         # Allow validation and modification of tool calls before execution
         # Using standard pre_call_hook
         #########################################################
+        hook_result: Dict[str, Any] = {}
         if proxy_logging_obj:
-            await self.pre_call_tool_check(
+            hook_result = await self.pre_call_tool_check(
                 name=name,
                 arguments=arguments,
                 server_name=server_name,
                 user_api_key_auth=user_api_key_auth,
                 proxy_logging_obj=proxy_logging_obj,
                 server=mcp_server,
             )
+            if "arguments" in hook_result:
+                arguments = hook_result["arguments"]
 
         # Prepare tasks for during hooks
         tasks = []
@@ -2227,8 +2251,16 @@ async def call_tool(
         # For OpenAPI servers, call the tool handler directly instead of via MCP client
         if mcp_server.spec_path:
             verbose_logger.debug(
-                f"Calling OpenAPI tool {name} directly via HTTP handler"
+                "Calling OpenAPI tool %s directly via HTTP handler", name
             )
+            if hook_result.get("extra_headers"):
+                verbose_logger.warning(
+                    "pre_mcp_call hook returned extra_headers for OpenAPI-backed "
+                    "MCP server '%s' — header injection is not supported for "
+                    "OpenAPI servers; headers will be ignored. Use SSE/HTTP "
+                    "transport to enable hook header injection.",
+                    server_name,
+                )
             tasks.append(
                 asyncio.create_task(
                     self._call_openapi_tool_handler(mcp_server, name, arguments)
@@ -2247,6 +2279,7 @@ async def call_tool(
                 raw_headers=raw_headers,
                 proxy_logging_obj=proxy_logging_obj,
                 host_progress_callback=host_progress_callback,
+                hook_extra_headers=hook_result.get("extra_headers"),
             )
 
         # For OpenAPI tools, await outside the client context

litellm/proxy/_types.py

@@ -2471,6 +2471,7 @@ class UserAPIKeyAuth(
         Any
     ] = None  # Expanded created_by user when expand=user is used
     end_user_object_permission: Optional[LiteLLM_ObjectPermissionTable] = None
+    jwt_claims: Optional[Dict] = None
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 

litellm/proxy/auth/user_api_key_auth.py

@@ -700,6 +700,7 @@ async def _user_api_key_auth_builder(  # noqa: PLR0915
                     )
                     if valid_token is not None:
                         api_key = valid_token.token or ""
+                        valid_token.jwt_claims = jwt_claims
                         do_standard_jwt_auth = False
                         # Fall through to virtual key checks
 
@@ -729,6 +730,7 @@ async def _user_api_key_auth_builder(  # noqa: PLR0915
                     team_membership: Optional[LiteLLM_TeamMembership] = result.get(
                         "team_membership", None
                     )
+                    jwt_claims: Optional[dict] = result.get("jwt_claims", None)
 
                     global_proxy_spend = await get_global_proxy_spend(
                         litellm_proxy_admin_name=litellm_proxy_admin_name,
@@ -757,6 +759,7 @@ async def _user_api_key_auth_builder(  # noqa: PLR0915
                             org_id=org_id,
                             end_user_id=end_user_id,
                             parent_otel_span=parent_otel_span,
+                            jwt_claims=jwt_claims,
                         )
 
                     valid_token = UserAPIKeyAuth(
@@ -803,6 +806,7 @@ async def _user_api_key_auth_builder(  # noqa: PLR0915
                         team_metadata=(
                             team_object.metadata if team_object is not None else None
                         ),
+                        jwt_claims=jwt_claims,
                     )
 
                     # Check if model has zero cost - if so, skip all budget checks

litellm/proxy/guardrails/guardrail_hooks/mcp_jwt_signer/__init__.py

@@ -0,0 +1,56 @@
+"""MCP JWT Signer guardrail — built-in LiteLLM guardrail for zero trust MCP auth."""
+
+from typing import TYPE_CHECKING
+
+from litellm.types.guardrails import SupportedGuardrailIntegrations
+
+from .mcp_jwt_signer import MCPJWTSigner, _mcp_jwt_signer_instance, get_mcp_jwt_signer
+
+if TYPE_CHECKING:
+    from litellm.types.guardrails import Guardrail, LitellmParams
+
+
+def initialize_guardrail(
+    litellm_params: "LitellmParams", guardrail: "Guardrail"
+) -> MCPJWTSigner:
+    import litellm
+
+    guardrail_name = guardrail.get("guardrail_name")
+    if not guardrail_name:
+        raise ValueError("MCPJWTSigner guardrail requires a guardrail_name")
+
+    optional_params = getattr(litellm_params, "optional_params", None)
+
+    def _get(key):  # type: ignore[no-untyped-def]
+        if optional_params is not None:
+            v = getattr(optional_params, key, None)
+            if v is not None:
+                return v
+        return getattr(litellm_params, key, None)
+
+    signer = MCPJWTSigner(
+        guardrail_name=guardrail_name,
+        event_hook=litellm_params.mode,
+        default_on=litellm_params.default_on,
+        issuer=_get("issuer"),
+        audience=_get("audience"),
+        ttl_seconds=_get("ttl_seconds"),
+    )
+    litellm.logging_callback_manager.add_litellm_callback(signer)
+    return signer
+
+
+guardrail_initializer_registry = {
+    SupportedGuardrailIntegrations.MCP_JWT_SIGNER.value: initialize_guardrail,
+}
+
+guardrail_class_registry = {
+    SupportedGuardrailIntegrations.MCP_JWT_SIGNER.value: MCPJWTSigner,
+}
+
+__all__ = [
+    "MCPJWTSigner",
+    "initialize_guardrail",
+    "_mcp_jwt_signer_instance",
+    "get_mcp_jwt_signer",
+]