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.
- Classic settings
- Policy Engine
Configure it on the server
Turn on Forward user claims ("Send a trusted X-User-Claims header to this MCP"). Click Save settings in the footer.
The setting is off by default. It is shown for servers that sign in with an upstream API key or no authentication. It is not shown for OAuth or OAuth passthrough servers, which already receive each person's own token, or for local packages.
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.
- Choose a recipe or start a blank rule under Forward user claims.
- Select the server and callers under Applies to, then choose whether to forward claims.
- 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"}
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-Claimsheader 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
Related
- Server access - decide who may call the server.
- API Tokens - the
mcpuserheader sets the person for token calls. - OneMCP - claims are forwarded on OneMCP calls too.
- Policy Engine overview - how cards, stages and priorities work.