Skip to main content

Claims forwarding

Updated on 3 November 2026.

Forward the caller's identity to a trusted MCP server. The gateway adds the signed-in person's identity to every request it forwards, so the server can apply its own per-user permissions, filtering or audit trail.

Choose the instructions for the mode that governs your MCP Gateway. See Switching from classic settings for what happens to stored settings when the engine is on.

Going further with the Policy Engine​

Open Govern > Policy Engine > MCP Gateway > Controls > Claims Forwarding. The Forward user claims section decides whether the server receives the caller's claims when a session is checked.

  1. Choose a recipe or start a blank rule under Forward user claims.
  2. Select the server and callers under Applies to, then choose whether to forward claims.
  3. Check Reads as, Save to draft, and test and publish.

The highest numeric priority wins. At equal priority, Not forwarded wins. Without a matching setting, claims are not forwarded.

Scope by people, Smart Groups, agents, or route to share identity only with the servers and callers that need it. The trust requirements below apply in both modes.

What the server receives​

The gateway adds an X-User-Claims header with compact JSON, on direct calls to the server and on calls routed through OneMCP:

X-User-Claims: {"v":1,"iss":"quilr-gateway","email":"user@example.com","preferred_username":"user@example.com","sub":"user_123","quilr_tenant_id":"tenant_abc","auth_method":"sso"}
ClaimAlways sentDescription
vYesClaims format version. Currently 1.
issYesIssuer. Always quilr-gateway.
emailYesThe person's email, in lowercase.
preferred_usernameYesSame as email.
subWhen availableThe person's Quilr user ID.
quilr_tenant_idWhen availableYour Quilr tenant ID.
auth_methodWhen availableHow the person signed in, for example sso.
oidWhen availableThe person's object ID from your identity provider.
tidWhen availableYour identity provider's tenant ID.
nameWhen availableThe person's display name.

Claims with no value are left out. New claims may be added later, so check v and ignore unused claims.

Trust​

  • The gateway always removes any X-User-Claims header a client sends, and adds its own only after the person has passed sign-in and server access checks.
  • Custom headers on the server cannot set X-User-Claims.
  • The value is plain JSON, not a signed token. Make sure your server only accepts traffic from the gateway, for example over a private network, before trusting it.
  • The header contains personal data. Turn it on only for servers approved to receive it.

Backend example​

import json

def authenticated_user(request):
# Only trust this header on traffic that arrived from the gateway.
raw_claims = request.headers.get("X-User-Claims")
if not raw_claims:
return None

claims = json.loads(raw_claims)
if claims.get("v") != 1 or claims.get("iss") != "quilr-gateway":
raise ValueError("Unsupported user claims")
return claims