BerriAI/litellm · error · ValueError

MCPJWTSigner guardrail requires a guardrail_name

Error message

MCPJWTSigner guardrail requires a guardrail_name

What it means

initialize_guardrail() for the MCP JWT signer reads guardrail_name from the guardrail entry and raises ValueError when it is missing. Like other guardrail init errors it surfaces at proxy startup, before any MCP traffic is signed.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/mcp_jwt_signer/__init__.py:18

"""MCP JWT Signer guardrail — built-in LiteLLM guardrail for zero trust MCP auth."""

from typing import TYPE_CHECKING, Final

from litellm.types.guardrails import SupportedGuardrailIntegrations

from .mcp_jwt_signer import MCPJWTSigner, 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: Final = guardrail.get("guardrail_name")
    if not guardrail_name:
        raise ValueError("MCPJWTSigner guardrail requires a guardrail_name")

    mode: Final = litellm_params.mode
    if mode != "pre_mcp_call":
        raise ValueError(
            f"MCPJWTSigner guardrail '{guardrail_name}' has mode='{mode}' but must use "
            "mode='pre_mcp_call'. JWT injection only fires for MCP tool calls."
        )

    optional_params: Final = getattr(litellm_params, "optional_params", None)

    def _get(key):
        if optional_params is not None:
            v: Final = getattr(optional_params, key, None)
            if v is not None:
                return v
        return getattr(litellm_params, key, None)

    signer: Final = MCPJWTSigner(

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add guardrail_name: <unique-name> to the mcp_jwt_signer guardrail entry
2. Validate generated configs contain guardrail_name before deploying

Example fix

# before
 guardrails:
   - guardrail: mcp_jwt_signer
     litellm_params:
       mode: pre_mcp_call

# after
 guardrails:
   - guardrail: mcp_jwt_signer
     guardrail_name: mcp-jwt-signer
     litellm_params:
       mode: pre_mcp_call

assert guardrail_entry.get("guardrail_name"), (  
    "mcp_jwt_signer entry requires guardrail_name"  
)

def has_guardrail_name(entry: object) -> bool:  
    return isinstance(entry, dict) and isinstance(entry.get("guardrail_name"), str) and bool(entry["guardrail_name"].strip())

When it happens

Trigger: A guardrails entry with guardrail: mcp_jwt_signer (or its initializer path) but no guardrail_name key.

Common situations: Guardrail YAML assembled by hand or template where the name line was dropped; entries generated programmatically without the name; configs migrated between guardrail formats.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• MCPJWTSigner: ttl_seconds must be > 0, got {resolved_ttl}
• MCPJWTSigner guardrail '{guardrail_name}' has mode='{mode}'
• MCP Security: guardrail_name is required
• mcp_tools_config is required, please set `mcp_tools` in your
• DynamoAI API key is required. Set DYNAMOAI_API_KEY environme

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/c6937ab756425067. Report an issue: GitHub.