Appendix - Technical Foundations: MCP Gateway
This appendix explains how the MCP Gateway environment is built, and above all how access control works: who is allowed to call which MCP tool, and which component makes that decision. Read it after (or alongside) the MCP Gateway module if you want to understand what happens behind each exercise.
Everything described here is deployed by OpenShift GitOps (Argo CD) from Helm charts in the lab repository, under automation/gitops/.
In One Sentence
The gateway validates a Keycloak JWT on every request, and authorizes each tool call by checking that the token carries a Keycloak role named after that tool — the backend MCP servers contain no security logic at all.
How This Differs from the MCP Server Module
| MCP Server | MCP Gateway | |
|---|---|---|
Who makes the decision |
The Kubernetes API server, using standard OpenShift RBAC |
The gateway (Envoy + Authorino), evaluating a CEL expression on a JWT |
Token presented by the client |
An OpenShift OAuth token ( |
A Keycloak access token (JWT), issued directly by Keycloak |
Role of Keycloak |
Identity store only — OpenShift OAuth uses it as its identity provider |
Token issuer, and the place where tool permissions are defined (groups and client roles) |
Granularity |
Kubernetes verb + resource (+ namespace) |
Individual MCP tool |
Where permissions are configured |
|
Keycloak groups and client roles, plus an |
Building Blocks
Keycloak
Red Hat Build of Keycloak runs in the keycloak namespace with a realm named keycloak. It is provided by the base environment. The setup Job keycloak-mcp-setup reads the Keycloak admin credentials from the keycloak-initial-admin secret and builds the authorization model through the Keycloak admin REST API (see The Authorization Model in Keycloak).
The mcp-cli Pod
The mcp-cli pod in the mcp-cli namespace runs opencode, pre-configured with the lab LLM and with the gateway:
"mcp-gateway": {
"type": "remote",
"url": "https://mcp-gateway.<cluster-domain>/mcp",
"headers": { "Authorization": "Bearer {env:GATEWAY_MCP_TOKEN}" }
}
opencode resolves {env:GATEWAY_MCP_TOKEN} when it starts, so you choose the user by exporting that user’s Keycloak token before starting opencode.
| The OpenShift MCP Server from the previous module is not behind this gateway. The two are separate endpoints, each with its own authentication model. |
Platform Side
Resources in the mcp-gateway and openshift-ingress namespaces:
-
MCP Gateway operator (Red Hat Connectivity Link), installed through OLM.
-
KuadrantCR — activates the policy engines: Authorino (authentication and authorization) and Limitador (rate limiting). It also sends traces to Jaeger. -
Gatewaymcp-gatewayinopenshift-ingress, implemented by Envoy through theopenshift-defaultGatewayClass. It has two listeners:-
mcp— hostnamemcp-gateway.<cluster-domain>, the public entry point, exposed through an edge-terminated Route. -
mcps— hostname*.mcp.internal, used internally to route traffic from the gateway to each backend MCP server.
-
-
ReferenceGrant— allows resources in themock-mcp-serversnamespace to attach to the Gateway inopenshift-ingress. -
AuthPolicymcp-tool-auth-policyon themcpslistener — the per-tool authorization check.
Tenant Side
Resources in the mock-mcp-servers namespace:
-
Three mock MCP servers —
inventory,paymentsandaccounts, each a FastMCP server with 5 tools, a Service, and anHTTPRouteon<name>.mcp.internal. -
MCPServerRegistrationper server, withprefix: "<name>_". This tells the broker to federate the server’s tools under prefixed names, such asinventory_list_products. -
MCPGatewayExtension— attaches the MCP broker (the MCP-aware router) to themcplistener. It also publishes OAuth protected resource metadata, so MCP clients can discover that Keycloak is the authorization server. -
AuthPolicymcp-gateway-authon the broker routemcp-gateway-route— requires a valid Keycloak JWT. -
RateLimitPolicymcp-gateway-ratelimit— 30 requests per minute, counted per JWTsubclaim (Exercise 5). -
Jaeger — receives OpenTelemetry traces from the gateway and the broker.
The Authorization Model in Keycloak
The setup Job models "which user can call which tool" entirely with standard Keycloak concepts:
Client mcp-gateway confidential client, used to obtain tokens
Client mock-mcp-servers/inventory roles: tool:list_products, tool:get_product, ...
Client mock-mcp-servers/payments roles: tool:list_transactions, tool:process_refund, ...
Client mock-mcp-servers/accounts roles: tool:list_accounts, tool:get_account, ...
(one client per MCPServerRegistration, named <namespace>/<name>)
Group team-a ◀── user1 gets all roles of inventory + accounts
Group team-b ◀── user2 gets all roles of payments
-
Each backend MCP server is represented by a Keycloak client.
-
Each tool is a client role named
tool:<tool-name>, using the tool’s unprefixed name. -
Groups receive client roles, and users inherit them through group membership.
A roles client scope with a client role mapper writes these roles into the access token under the resource_access claim. A token issued to user1 contains:
"resource_access": {
"mock-mcp-servers/inventory": { "roles": ["tool:list_products", "tool:get_product", "..."] },
"mock-mcp-servers/accounts": { "roles": ["tool:list_accounts", "tool:get_account", "..."] }
}
The basic scope is also added so the token contains the sub claim used for per-user rate limiting, and the realm’s access token lifespan is set to 8 hours.
Request Flow
curl .../token (client mcp-gateway, user1) ──▶ Keycloak ──▶ JWT with resource_access
client ──▶ Route ──▶ Gateway listener "mcp" ──▶ broker
│ AuthPolicy mcp-gateway-auth: valid JWT for the realm? no ──▶ 401
│ RateLimitPolicy: under 30 req/min for sub? no ──▶ 429
▼
Broker
│ tools/list ──▶ federated list of all 17 tools
│ tools/call inventory_list_products
│ strips the prefix, forwards to inventory.mcp.internal
│ with headers x-mcp-servername: mock-mcp-servers/inventory
│ x-mcp-toolname: list_products
▼
Gateway listener "mcps"
│ AuthPolicy mcp-tool-auth-policy (CEL):
│ "tool:" + x-mcp-toolname in resource_access[x-mcp-servername].roles ?
▼
yes ──▶ inventory MCP server no ──▶ 403 "Insufficient permissions for this tool"
The tool-level rule only applies when the x-mcp-toolname header is present, that is, on tool calls. Protocol traffic such as initialize and tools/list only requires a valid token — which is why user1 sees all 17 tools in Exercise 3, but cannot call the payments tools in Exercise 4.
The authorization check itself is a single CEL expression in the AuthPolicy:
authorization:
tool-access-check:
when:
- predicate: "request.headers.exists(h, h == 'x-mcp-toolname')"
patternMatching:
patterns:
- predicate: |
('tool:' + request.headers['x-mcp-toolname']) in
(has(auth.identity.resource_access) &&
auth.identity.resource_access.exists(p, p == request.headers['x-mcp-servername'])
? auth.identity.resource_access[request.headers['x-mcp-servername']].roles
: [])
The backend MCP servers contain no authentication or authorization logic at all — everything is enforced by Envoy and Authorino in front of them.
How to Control Who Can Do What
-
Give a team access to a whole server — map all of that server’s client roles to the team’s group.
-
Give access to a single tool — assign only the corresponding
tool:<name>client role, to a group or directly to a user, in the Keycloak admin console. -
Add a new MCP server — create an
HTTPRouteandMCPServerRegistrationfor it, a Keycloak client named<namespace>/<registration-name>, onetool:<name>client role per tool, and the group mappings. No change is needed in theAuthPolicy.
Changes take effect on the next token: a user must request a new access token to receive updated roles.
Inspect It Yourself
These commands use the USER1_TOKEN variable created at the beginning of the MCP Gateway module.
-
Decode the payload of `user1’s JWT and look at the claims the gateway relies on:
echo "$USER1_TOKEN" | jq -R 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | . + ("=" * ((4 - length % 4) % 4)) | @base64d | fromjson | {preferred_username, sub, resource_access}' -
List the MCP-related policies and where they are attached:
oc get authpolicy,ratelimitpolicy -A -
View the tool-level authorization rule:
oc get authpolicy mcp-tool-auth-policy -n openshift-ingress -o jsonpath='{.spec.rules.authorization}' | jq -
View the federated servers and their tool prefixes:
oc get mcpserverregistration -n mock-mcp-servers \ -o custom-columns=NAME:.metadata.name,PREFIX:.spec.prefix,ROUTE:.spec.targetRef.name
Key Points to Remember
-
Authentication and authorization are moved out of the MCP servers and into the gateway, so every server behind it gets the same security model for free.
-
Permissions are data in Keycloak, not code: one client per server, one role per tool, groups per team.
-
Tool discovery is not filtered per user. Authorization is enforced when a tool is called.
-
This token is not interchangeable with the one used in the MCP Server module: the gateway expects a Keycloak JWT that it validates against the realm’s issuer.
-
Gateway authorization and Kubernetes RBAC are complementary. The gateway answers "may this user call this tool?", while RBAC answers "may this user perform this operation on the cluster?". Placing an MCP server that uses token passthrough behind the gateway would combine both checks — this lab demonstrates each layer separately.