MCP Identity Routes
This page tells an operator how to add an MCP route on LiteLLM that relays the identity of each caller to the upstream server. An identity route is a route where the client sends its own Keycloak token and the upstream makes the access decision. Three routes use this shape today: engram, kubernetes and dns. For how a client connects to a route, read MCP Gateway Client Setup.
The shape of an identity route
Section titled “The shape of an identity route”Each request carries two credentials. The header x-litellm-api-key holds the LiteLLM virtual key of the client, and LiteLLM uses it for admission, spend and rate limits. The header Authorization holds a Keycloak access token, and LiteLLM forwards it to the upstream without a change. The upstream tests the token and decides what the caller can do.
Two kinds of caller use a route:
- A person signs in through the browser. Claude Code and other clients register their own Keycloak client through DCR (dynamic client registration, RFC 7591) and then run PKCE.
- An agent uses the
client_credentialsgrant of a confidential client that Terraform owns, for exampledns-agent-triage.
The two kinds get different tokens from the same realm. A route that works for an agent does not prove that it works for a person. The reason is in Roles and DCR clients.
| Route | Audience in the token | Authorization data | Keycloak file |
|---|---|---|---|
engram |
mcp-public |
none, every realm user | tf/keycloak/mcp_audience.tf |
kubernetes |
https://llm.fzymgc.house/kubernetes/mcp |
groups and email, read by k3s RBAC |
tf/keycloak/mcp_kubernetes.tf |
dns |
https://llm.fzymgc.house/dns/mcp |
client roles of dns-control, and preferred_username |
tf/keycloak/mcp_dns.tf |
Roles and DCR clients
Section titled “Roles and DCR clients”The realm keeps the default anonymous registration policies of Keycloak. One of them turns off full scope on every client that DCR creates. If full scope is off, a role mapper puts a role into the token only through a role scope mapping. That mapping must be on the client or on one of its client scopes. A client that Terraform creates keeps full scope, so its tokens carry every role of the user.
The result is a trap. A route that authorizes on client roles works for an agent and fails for a person, with no error in Keycloak. The person token has the right aud, but its roles claim is empty. The upstream then refuses the token with 401 and error="invalid_token". Phase 3 of the DNS v2 work hit this on the dns route. The fix was a role scope mapping on the client scope mcp-dns.
Groups do not have this problem. A group membership mapper does not depend on full scope. This is why kubernetes, which authorizes on groups, works for a person with no role scope mapping.
Do not change the registration policies of the realm, and do not turn on full scope for a DCR client. Either change gives every DCR client, including those of engram and kubernetes, every role of its user.
Add a route
Section titled “Add a route”Use the dns route as the worked example. Replace <name> with the route name.
Keycloak
Section titled “Keycloak”Put all of the following in one file, tf/keycloak/mcp_<name>.tf:
- Create a client scope named
mcp-<name>withinclude_in_token_scope = true. - Add a
keycloak_openid_audience_protocol_mapperto the scope. Setincluded_custom_audiencetohttps://llm.fzymgc.house/<name>/mcpand write it to the access token only. The audience is the resource URL of the route, not the host of the upstream. - If the upstream authorizes on client roles, add a
keycloak_openid_user_client_role_protocol_mapperto the scope. Keepmultivalued = true, or Keycloak writes the first role only. - For each role that a person token needs, add a
keycloak_generic_role_mapperwithclient_scope_idset to the scope. Map only the roles that the route needs. Thednsroute mapsdns-readerand nothing else. - If the upstream authorizes on groups, attach the realm scope
groupsinstead of steps 3 and 4. - If the upstream names the caller in a log, add a
keycloak_openid_user_property_protocol_mapperthat writesusernametopreferred_username. A DCR client gets only thebasicdefault scope, and that scope has nopreferred_username. - Add the scope to
keycloak_realm_optional_client_scopesintf/keycloak/client_scopes.tf. A DCR client can request only a realm optional scope.
A static public client, such as mcp-dns, is a fallback for a client that cannot use DCR. If you add one, give it the route scope as a default scope. Its resource keycloak_openid_client_optional_scopes is authoritative, so it must repeat the realm optional list without the route scope.
Do not put the built-in scope roles in the default scopes of a route client. Its audience resolve mapper adds the aud of every client whose roles are in the token. An MCP token then also opens the other surfaces of those clients, for example the REST API of dns-control.
Do not attach the route scope to mcp-public or to basic. If you attach it, every realm token opens the route.
LiteLLM
Section titled “LiteLLM”Add the route to mcp_servers in argocd/app-configs/litellm-chart/values.yaml:
<name>: server_id: <name> url: "http://<service>.<namespace>.svc.cluster.local:<port>/mcp" transport: http auth_type: none extra_headers: ["Authorization"] oauth_passthrough: truePin server_id. An access group stores server ids, and without a pin an edit of the route changes the id and orphans every grant.
Set auth_type: none explicitly. LiteLLM treats the route as per-user auth only for none, and then skips its health probe. If auth_type is absent, the probe sends no credential, gets 401, and the route reads unhealthy.
Do not give the route static_headers or an authentication_token so that the probe can authenticate. LiteLLM applies static_headers after the relayed header. A static Authorization therefore replaces the token of every caller, and every call runs as the owner of the static credential.
The upstream must serve its own RFC 9728 protected-resource document. LiteLLM relays it at https://llm.fzymgc.house/.well-known/oauth-protected-resource/<name>/mcp with only resource rewritten, and answers 502 when the upstream has none. The document must name Keycloak as the authorization server and list mcp-<name> in scopes_supported. A client requests the scopes on that list.
Virtual keys
Section titled “Virtual keys”LiteLLM v1.103.0-rc.1 applies these rules to the MCP routes that a key reaches. Plan 03-13 measured them:
- A key with no
object_permissionlist reaches every route when its user has the roleproxy_admin. For any other user, it reaches no route. - A key with an explicit
object_permission.mcp_serverslist reaches only the routes on the list. This holds for aproxy_adminuser and for an empty list. - An access group adds its routes to the list of each key it holds.
- A refusal on key scope is HTTP
403withThe key is not allowed to access the requested MCP servers.
A key that Terraform owns gets a route through an access group in tf/litellm/access_groups.tf, because the provider has no argument for object_permission. For the other keys, read Minting and scoping virtual keys.
The upstream
Section titled “The upstream”The upstream tests each token itself:
- It tests the signature and the issuer against the realm.
- It requires
audto hold the resource URL of the route. - It requires the role or group that the route needs, and a future
exp. - It reads identity from the token only, never from a forwarded header, because any pod in the cluster can set a header.
- It refuses a LiteLLM virtual key (prefix
sk-) inAuthorization.
On a refusal, it answers 401 with WWW-Authenticate: Bearer error="invalid_token", resource_metadata="<the relayed document URL>". apps/dns-control/internal/mcpserver/verify.go is the reference.
Read a refusal
Section titled “Read a refusal”| Response | Cause | Next step |
|---|---|---|
401, challenge with resource_metadata and no error |
LiteLLM got no Authorization header |
Make sure that the client signed in and sends the token |
401, challenge with error="invalid_token" |
The upstream refused the token | Decode the token, as in the next section |
403, The key is not allowed to access the requested MCP servers |
LiteLLM refused the virtual key | Grant the route to the key |
502 on the protected-resource document |
The upstream serves no RFC 9728 document | Fix the upstream |
After a sign-in, Claude Code shows Got new credentials, but <name> rejected them on reconnect for any 401. The message does not tell you which component refused. Read the status and the challenge instead.
Prove a route for a person
Section titled “Prove a route for a person”Test the route with a person token, not only an agent token. An agent token comes from a client with full scope, so it can pass where a person token fails.
- Add the route in Claude Code and sign in, as in MCP Gateway Client Setup.
- Run the probe below in your own shell. It reads the token that Claude Code stored, decodes its claims, and sends
initializeto the route. It prints no token and no key. - Make sure that
audholds the route URL and that the roles or groups that the route needs are present. - Make sure that the status is
200. If it is not, use the table in Read a refusal. - Make sure that the log of the upstream names you. For
dns, querydefault.otel_logsin ClickStack formcp tool callwith yourpreferred_username.
ROUTE=dns # the route name, as in https://llm.fzymgc.house/<name>/mcp(set -euo pipefailTOKEN="$(security find-generic-password -s 'Claude Code-credentials' -w \ | jq -r --arg r "/$ROUTE/mcp" '[.. | objects | select((.serverUrl? // "") | endswith($r)) | .accessToken? // empty] | first // empty')"[ -n "$TOKEN" ] || { echo "no stored token for $ROUTE"; exit 1; }KEY="$(jq -r --arg r "$ROUTE" '.mcpServers[$r].headers["x-litellm-api-key"] | split(" ") | last' ~/.claude.json)"cut -d. -f2 <<<"$TOKEN" | tr '_-' '/+' | awk '{while (length($0) % 4) $0 = $0 "="; print}' | base64 -d \ | jq -c --argjson now "$(date +%s)" '{azp, aud, scope, preferred_username, groups, resource_access, exp_in_s: (.exp - $now)}'curl -sS -o /dev/null -w 'initialize: HTTP %{http_code}\n' -X POST "https://llm.fzymgc.house/$ROUTE/mcp" \ -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ -H "x-litellm-api-key: Bearer $KEY" -H "Authorization: Bearer $TOKEN" \ --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"route-probe","version":"0"}}}')If exp_in_s is negative, the token expired. Sign in again before you read the status, because an expired token also gets 401.
If a change to Keycloak does not show in a new token, remove the route from Claude Code and add it again. The next sign-in registers a new DCR client.