JWT Bearer

The JWT bearer flow validates an access token presented by an AI agent against a JWKS endpoint. Unlike the earlier http server-guarded approach used elsewhere in Zilla, the mcp server binding validates this token itself, through its own options.authorization field, before the request reaches the MCP proxy or any upstream tool provider. Token validation reuses the same jwt guard used anywhere else in the platform: point it at an issuer and audience, and either let it fetch the identity provider's .well-known/jwks.json file automatically or provide the signing keys manually.

Configuring the Guard

Define a jwt guard with the identity provider's issuer and audience, then reference it from the mcp server binding's options.authorization:

guards:
  agent_jwt:
    type: jwt
    options:
      issuer: https://auth.example.com
      audience: https://mcp.example.com

bindings:
  north_http_server:
    type: http
    kind: server
    options:
      access-control:
        policy: cross-origin
    routes:
      - when:
          - headers:
              ":path": /mcp
        exit: north_mcp_server

  north_mcp_server:
    type: mcp
    kind: server
    options:
      authorization:
        agent_jwt:
          credentials: "Bearer {credentials}"
    exit: north_mcp_proxy

The credentials template, Bearer {credentials}, is matched against the inbound Authorization header. A request with no Authorization header is admitted as unauthorized, the same as an unauthenticated request reaching an unguarded route anywhere else in Zilla; a request whose header doesn't match the template, or whose extracted token the agent_jwt guard rejects, is turned away at north_mcp_server with a 401 response and a WWW-Authenticate challenge, before it ever reaches the MCP proxy or an upstream tool provider.

See the jwt guard reference for the full set of options fields, including manual key configuration and role claims, and the mcp server binding reference for options.authorization.

Per-Tool Authorization

options.authorization authenticates the session once. To also restrict which tools, prompts, or resources an authenticated session can use, add routes[].guarded on the mcp proxy or mcp client binding downstream, requiring specific roles from the same guard on a per-route basis. See Centralized Auth for how the two layers combine.