Skip to content

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.

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_credentials grant of a confidential client that Terraform owns, for example dns-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

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.

Use the dns route as the worked example. Replace <name> with the route name.

Put all of the following in one file, tf/keycloak/mcp_<name>.tf:

  1. Create a client scope named mcp-<name> with include_in_token_scope = true.
  2. Add a keycloak_openid_audience_protocol_mapper to the scope. Set included_custom_audience to https://llm.fzymgc.house/<name>/mcp and write it to the access token only. The audience is the resource URL of the route, not the host of the upstream.
  3. If the upstream authorizes on client roles, add a keycloak_openid_user_client_role_protocol_mapper to the scope. Keep multivalued = true, or Keycloak writes the first role only.
  4. For each role that a person token needs, add a keycloak_generic_role_mapper with client_scope_id set to the scope. Map only the roles that the route needs. The dns route maps dns-reader and nothing else.
  5. If the upstream authorizes on groups, attach the realm scope groups instead of steps 3 and 4.
  6. If the upstream names the caller in a log, add a keycloak_openid_user_property_protocol_mapper that writes username to preferred_username. A DCR client gets only the basic default scope, and that scope has no preferred_username.
  7. Add the scope to keycloak_realm_optional_client_scopes in tf/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.

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: true

Pin 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.

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_permission list reaches every route when its user has the role proxy_admin. For any other user, it reaches no route.
  • A key with an explicit object_permission.mcp_servers list reaches only the routes on the list. This holds for a proxy_admin user 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 403 with The 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 tests each token itself:

  • It tests the signature and the issuer against the realm.
  • It requires aud to 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-) in Authorization.

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.

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.

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.

  1. Add the route in Claude Code and sign in, as in MCP Gateway Client Setup.
  2. Run the probe below in your own shell. It reads the token that Claude Code stored, decodes its claims, and sends initialize to the route. It prints no token and no key.
  3. Make sure that aud holds the route URL and that the roles or groups that the route needs are present.
  4. Make sure that the status is 200. If it is not, use the table in Read a refusal.
  5. Make sure that the log of the upstream names you. For dns, query default.otel_logs in ClickStack for mcp tool call with your preferred_username.
Terminal window
ROUTE=dns # the route name, as in https://llm.fzymgc.house/<name>/mcp
(
set -euo pipefail
TOKEN="$(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.