Chapter 1. MCP server

Procedure

1. Install the MCP gateway.

   For information about how to install the MCP gateway, see "Install the MCP gateway (Red Hat Connectivity Link)".

   After installation, the controller automatically creates the HTTPRoute for gateway access. The MCP gateway acts as a reverse proxy that aggregates multiple MCP servers into a single endpoint and provides a layer for authentication and rate limiting.

Procedure

1. Check the status of your deployment by running the following command:

   $ oc get pods -n gateway-namespace -l "app.kubernetes.io/name=mcp-gateway"

   Note

   This example uses the namespace "gateway-namespace" for installing the gateway. If you install the gateway in a different namespace than "gateway-namespace", use that namespace instead throughout the procedure.

   Example

   NAME                                      READY   STATUS    RESTARTS   AGE
   mcp-gateway-controller-594b9649cf-zstfw   1/1     Running   0          22s

2. Ensure that the MCP gateway Extension exists by running the following command:

   $ oc get mcpgatewayextension -A

   Example

   NAMESPACE          NAME          READY   AGE
   gateway-namespace  mcp-gateway           105s

3. Verify the broker-router deployment by running the following command:

   $ oc logs -n gateway-namespace deployment/mcp-gateway

4. Verify EnvoyFilter was created in the gateway namespace by running the following command:

   $ oc get envoyfilter -n gateway-namespace -l app.kubernetes.io/managed-by=mcp-gateway-controller

Procedure

1. Before creating the HTTPRoute, verify the exact name of your MCP server service by entering the following command:

   $ oc get svc -n openshift-mcp-server

   Ensure that the backendRefs.name field in the following manifest matches the NAME output of your service. For example, openshift-mcp-server.

2. Create the HTTPRoute for the MCP server by running the following command:

   $ oc apply -f - <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: mcp-api-key-server-route
     namespace: openshift-mcp-server
   spec:
     parentRefs:
     - group: gateway.networking.k8s.io
       kind: Gateway
       name: mcp-gateway
       namespace: gateway-namespace
       sectionName: mcp
     hostnames:
     - ${MCP_SERVER_HOST}
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /mcp
       backendRefs:
       - name: openshift-mcp-server
         port: 8080
   EOF

   ${MCP_SERVER_HOST} is the hostname of your MCP gateway route (for example, mcp-gateway.apps.<cluster-name>.<domain-name>).

   This HTTPRoute enables the MCP gateway to route traffic to your MCP server instance and is referenced in the MCPServerRegistration resource.

3. Create an MCP server Registration Resource by running the following command:

   $ oc apply -f - <<EOF
   apiVersion: mcp.kuadrant.io/v1alpha1
   kind: MCPServerRegistration
   metadata:
     name: my-mcp-server-reg
     namespace: openshift-mcp-server
   spec:
     prefix: "openshift_"
     targetRef:
       group: "gateway.networking.k8s.io"
       kind: "HTTPRoute"
       name: "mcp-api-key-server-route"
       namespace: openshift-mcp-server
   EOF

   • metadata.name: Provide a name for the MCP server registration object.
   • metadata.namespace: The namespace for the MCP server, which is openshift-mcp-server.
   • spec.targetRef.name: The name of your MCP server HTTPRoute. You can find this by running the command: oc get httproute -n openshift-mcp-server.
   • spec.targetRef.namespace: The namespace for the MCP server HTTPRoute, which is openshift-mcp-server.

4. Verify the registration status by running the following commands:

   $ oc wait --for=condition=Ready mcpsr/my-mcp-server-reg -n openshift-mcp-server --timeout=120s
   $ oc get mcpsr -A

   Example output

   NAMESPACE             NAME                PREFIX      TARGET                     PATH   READY   TOOLS   CREDENTIALS   AGE
   openshift-mcp-server  my-mcp-server-reg   myserver_   mcp-api-key-server-route   /mcp   True    4                     30s

   The READY column should display True and the TOOLS column should show the number of tools discovered.

   If the status is not ready, check the MCP server Registration conditions for details by running the following command:

   $ oc describe mcpsr my-mcp-server-reg -n openshift-mcp-server

5. Check the controller logs by running the following command:

   $ oc logs -n gateway-namespace deployment/mcp-gateway-controller

6. Check the broker logs for tool discovery by running the following command:

   $ oc logs -n gateway-namespace deployment/mcp-gateway

7. Verify that your MCP server tools are available through the MCP gateway:

   1. Initialize the MCP session and capture session ID by using -D to dump headers to a file, and then reading the session ID by running the following command:

      $ curl -s -D /tmp/mcp_headers -X POST http://mcp-gateway.apps.<cluster-name>.<domain-name>:8001/mcp  \
        -H "Content-Type: application/json" \
        -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'

      <cluster-name>.<domain-name> is the name and domain of your cluster.

   2. Extract the MCP session ID from response headers by running the following commands:

      $ SESSION_ID=$(grep -i "mcp-session-id:" /tmp/mcp_headers | cut -d' ' -f2 | tr -d '\r')
      
      $ echo "MCP Session ID: $SESSION_ID"

   3. List tools by using the session ID in the following command:

      $ curl -X POST http://mcp-gateway.apps.<cluster-name>.<domain-name>:8001/mcp \
        -H "Content-Type: application/json" \
        -H "mcp-session-id: $SESSION_ID" \
        -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

      <cluster-name>.<domain-name> is the name and domain of your cluster.

   4. Clean up by running the following command:

      $ rm -f /tmp/mcp_headers

      You should now see your MCP server tools in the response, prefixed with your configured prefix value, such as openshift_.

Procedure

1. Add the following lines to your client configuration file:

   • For Claude Desktop: claude_desktop_config.json file

   • For Claude Code (CLI): .mcp.json file

     {
       "mcpServers": {
         "openshift": {
           "type": "http",
           "url": "<url of the mcp gateway>/mcp"
         }
       }
     }

     <url of the mcp gateway> is the hostname you configured during MCP gateway installation.

2. Accept the CA certificate when prompted by the client.

Procedure

1. Configure RBAC enforcement by extending ClusterRoles, ClusterRoleBindings, Roles, and Rolebindings.

   Use the following example RBAC YAML file to extend ClusterRoles, ClusterRoleBindings, Roles, and Rolebindings:

   Example RBAC settings YAML file

     apiVersion: rbac.authorization.k8s.io/v1
     kind: ClusterRole
     metadata:
       name: acm-managed-clusters
     rules:
       ...
     ---
     apiVersion: rbac.authorization.k8s.io/v1
     kind: ClusterRoleBinding
     metadata:
       name: acm-managed-clusters
       ...
     ---
     apiVersion: rbac.authorization.k8s.io/v1
     kind: Role
     metadata:
       name: acm-cluster-proxy-discovery
       namespace: multicluster-engine
       ...
     ---
     apiVersion: rbac.authorization.k8s.io/v1
     kind: RoleBinding
     metadata:
       name: acm-cluster-proxy-discovery
       namespace: multicluster-engine
       ...

2. Apply the RBAC configuration by saving the preceding example to a file (for example, rbac-values.yaml), and then run the following command:

   $ oc apply -f rbac-values.yaml

Procedure

1. Configure OAuth metadata discovery by setting environment variables on the MCP gateway broker-router deployment by running the following command:

   $ oc set env mcp-gateway/gateway-namespace -n mcp-system\
   OAUTH_RESOURCE_NAME="MCP Server" \
   OAUTH_RESOURCE="https://<mcp_gateway_host>/mcp" \
   OAUTH_AUTHORIZATION_SERVERS=<authorization_server_url> \
   OAUTH_BEARER_METHODS_SUPPORTED="header" \
   OAUTH_SCOPES_SUPPORTED=<oauth-scopes-supported>

   Note

   These environment variables enable the OAuth 2.0 Protected Resource Metadata endpoint that clients use for authentication discovery.

   • For <oauth-scopes-supported> use either:

     • For Entra ID: "api://<MCP_SERVER_CLIENT_ID>/mcp-server"
     • For Keycloak: "mcp-server"

   • For <authorization_server_url> use either:

     • Entra ID: https://login.microsoftonline.com/<tenant-id>/v2.0
     • Keycloak: https://<keycloak_host>/realms/<realm>

2. Create the HTTPRoute for OAuth discovery by running the following command:

   $ oc apply -f - <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: mcp-gateway-oauth-metadata
     namespace: gateway-namespace
   spec:
     parentRefs:
     - group: gateway.networking.k8s.io
       kind: Gateway
       name: mcp-gateway
       namespace: gateway-namespace
       sectionName: mcp
     hostnames:
     - ${MCP_GATEWAY_HOST}
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /.well-known/oauth-protected-resource
       backendRefs:
       - name: mcp-gateway
         port: 8080
   EOF

   ${MCP_GATEWAY_HOST} is the fully qualified domain name for your MCP gateway (for example, mcp.127-0-0-1.sslip.io).

   This route enables clients to discover OAuth metadata, which is required for the authentication flow. Without this route, clients receive a 404 error when attempting OAuth discovery.

3. Configure the IdP (Entra ID or Keycloak) App Registration:

   • For Entra ID:

     1. In the Azure Portal or Entra admin center, go to your Entra ID App Registration.
     2. Under Expose an API, add a custom scope named mcp-server.
     3. Ensure that the following scopes are available: openid, offline_access, and mcp-server.

     4. If required by your organization, grant admin consent for these scopes.

        For more information about configuring Entra ID app registrations, see "Microsoft Entra ID".

   • For Keycloak:

     1. Ensure that the following required scopes exist in your Keycloak realm:

        • openid (built-in)
        • offline_access (built-in)
        • mcp-server (custom — create it if it does not exist)

     2. In the admin console, go to Realm Settings > Client Registration > Authenticated Access Policies, and add these scopes to the realm’s DCR Allowed Client Scopes policy.

        For more information about Keycloak, see "Red Hat build of Keycloak".

4. Configure certificate trust for JWT validation by mounting the IdP’s CA certificate into the Authorino deployment by running the following commands:

   Important

   Skip this step if the IdP uses a publicly trusted certificate.

   $ oc create configmap idp-ca --from-file=ca.crt=/path/to/idp-ca.crt -n kuadrant-system

   $ oc patch deployment authorino -n kuadrant-system --type=json -p='[
     {
       "op": "add",
       "path": "/spec/template/spec/volumes/-",
       "value": {"name": "idp-ca", "configMap": {"name": "idp-ca"}}
     },
     {
       "op": "add",
       "path": "/spec/template/spec/containers/0/volumeMounts/-",
       "value": {"name": "idp-ca", "mountPath": "/etc/ssl/certs/idp-ca.crt", "subPath": "ca.crt"}
     }
   ]'

   This ensures that Authorino can verify JWT token signatures from the IdP.

5. Configure the MCP gateway authentication by applying the authentication policy that validates JWT tokens by running the following command:

   $ oc apply -f - <<EOF
   apiVersion: kuadrant.io/v1
   kind: AuthPolicy
   metadata:
     name: mcp-auth-policy
     namespace: gateway-namespace
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway
       name: mcp-gateway
       sectionName: mcp
     defaults:
       when:
         - predicate: "!request.path.contains('/.well-known')"
       rules:
         authentication:
           'idp':
             jwt:
               issuerUrl: <authorization_server_url>
         response:
           unauthenticated:
             code: 401
             headers:
               'WWW-Authenticate':
                 value: Bearer resource_metadata=https://<mcp_gateway_host>/.well-known/oauth-protected-resource/mcp
               body:
                 value: |
                   {
                     "error": "Unauthorized",
                     "message": "Authentication required."
                   }
   
           success:
             headers:
               authorization:
                 plain:
                   expression: "request.headers['authorization']"
   
   EOF

   • For <authorization_server_url> use either:

     • Entra ID: http://login.microsoftonline.com/<tenant-id>/v2.0
     • Keycloak: https://<keycloak_host>/realms/<realm>

6. Grant the authenticated user permissions on the cluster by creating a ClusterRoleBinding by using a file similar to the following:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: oidc-mcp-cluster-reader
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: view
   subjects:
   - apiGroup: rbac.authorization.k8s.io
     kind: User
     name: <issuer_url>#<username>

   • name: The user subject, in the format <issuer_url>#<username>.
   • Adjust the ClusterRole (for example, view) to the level of access the user requires.

Verification

1. Verify OAuth Discovery by testing that the broker now serves OAuth discovery information by running the following command:

   curl ${MCP_GATEWAY_HOST}/.well-known/oauth-protected-resource

   For ${MCP_GATEWAY_HOST} use your MCP gateway domain.

   The command should show OAuth 2.0 Protected Resource Metadata similar to the following:

   Example

   {
     "resource_name": "MCP Server",
     "resource": "http://mcp.127-0-0-1.sslip.io:8001/mcp",
     "authorization_servers": [
       "https://login.microsoftonline.com/<tenant-id>/v2.0"
     ],
     "bearer_methods_supported": [
       "header"
     ],
     "scopes_supported": [
       "mcp-server",
     ]
   }

2. Test that protected endpoints now require authentication by running the following command:

   $ curl -v ${MCP_GATEWAY_HOST}/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

   • For ${MCP_GATEWAY_HOST} use your MCP gateway domain.

     Example

     {
       "error": "Unauthorized",
       "message": "Authentication required."
     }

Procedure

1. Ensure that your identity provider includes necessary group/role claims in the issued JWT tokens.

   The issued OAuth token should include claims similar to:

   Example

   {
     "resource_access": {
       "mcp-ns/openshift-mcp-server": {
         "roles": ["pods_list", "events_list", "nodes_list", "deployments_get"]
       },
       "mcp-ns/geometry-mcp-server": {
         "roles": ["pods_list", "events_list", "nodes_list", "deployments_get"]
       }
     }
   }

   • The namespace should match the namespace of the MCPServerRegistration CR.
   • The “roles” represent the allowed tools. In this example, pods_list, events_list, nodes_list, deployments_get.

2. Configure tool-level authorization by applying an AuthPolicy that enforces tool-level access control by running the following command:

   $ oc apply -f - <<EOF
   apiVersion: kuadrant.io/v1
   kind: AuthPolicy
   metadata:
     name: mcp-tool-auth-policy
     namespace: openshift-mcp-server
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway
       name: mcp-gateway
       sectionName: mcp
     rules:
       authentication:
         'idp':
           jwt:
             issuerUrl: <authorization_server_url>
       authorization:
         'tool-access-check':
           patternMatching:
             patterns:
               - predicate: |
                   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 : [])
       response:
         unauthenticated:
           headers:
             'WWW-Authenticate':
               value: Bearer resource_metadata=https://<mcp_gateway_host>/.well-known/oauth-protected-resource/mcp
           body:
             value: |
               {
                 "error": "Unauthorized",
                 "message": "MCP Tool Access denied: Authentication required."
               }
         unauthorized:
           body:
             value: |
               {
                 "error": "Forbidden",
                 "message": "MCP Tool Access denied: Insufficient permissions for this tool."
               }
   EOF

   • For <authorization_server_url> use either:

     • Entra ID: login.microsoftonline.com/<tenant-id>/v2.0
     • Keycloak: https://<keycloak_host>/realms/<realm>
   • spec.sectionName targets the MCP server Listener.
   • <cluster-name>.<domain-name> is the name and domain of your cluster.

Verification

1. Test that authorization now controls tool access by setting up the MCP Inspector:

   1. Start MCP Inspector (requires Node.js/npm) by running the following command:

      $ npx @modelcontextprotocol/inspector@latest &
      INSPECTOR_PID=$!

   2. Wait for services to start by running the following command:

      $ sleep 3

   3. Open MCP Inspector by going to the following URL: http://localhost:6274/?transport=streamable-http&serverUrl=https://<mcp_gateway_host>/mcp.

      Replace <mcp_gateway_host> with the fully qualified domain name of your MCP gateway

2. To stop the services later, run the following command:

   $ kill $INSPECTOR_PID

3. Authenticate using a user account configured with the required role claims in your identity provider.

4. Try the following allowed tools:

   • pods_list
   • events_list
   • nodes_list
   • deployments_get

5. Try this restricted tool: pods_delete

   Since this tool is restricted, you should get a 403 Forbidden error.

6. Monitor authorization decisions:

   1. Check the AuthPolicy status by running the following command:

      $ oc get authpolicy -A

   2. View the authorization logs by running the following command:

      $ oc logs -n kuadrant-system -l authorino-resource=authorino

Procedure

1. To enable the ossm toolset, add or update the config.toml file to include the ossm toolset:

   Adding ossm toolset

   toolsets = ["core", "ossm"]

2. Configure the ossm toolset similar to the following:

   Adding ossm toolset configuration

   [toolset_configs.kiali]
   url = "https://<kiali_route>"
   # insecure = true
   # certificate_authority = "/path/to/ca.crt"

   Important

   If the table is missing or invalid, the server does not start.

   • The ossm toolset reads its settings from [toolset_configs.kiali].

   • url is required.

     Use an http:// or https:// URL that includes a host. When url is https:// and insecure is false, set certificate_authority to the CA file for the Kiali certificate. A relative CA path is resolved from the directory that contains the TOML file.

   • Outside production, insecure = true skips certificate verification.

   • read_only = true (default) hides ossm_manage_istio_config:

     To set the assistant’s permission to create, update, or delete the mesh configuration:

     • Not allowed: set read_only = true.

     • Is allowed: leave read_only unset, or set it to false.

       For information about how to apply configuration changes, see "Applying configuration changes to the MCP server for Red Hat OpenShift".

3. Bind the caller’s identity to the operator-provided kiali-viewer (read) or kiali (read/write) ClusterRole.

   The server uses your existing Kubernetes credentials (from kubeconfig or in-cluster) to set a bearer token for Kiali calls. An HTTP Authorization header passed to the MCP HTTP endpoint is not required for Kiali; Kiali calls use the server’s configured token.

   Kiali enforces access with that token (namespace get/list and, for writes and logs, resource RBAC). Tools advertise this as RBAC metadata:

   • Bounded for tools whose Kubernetes checks are derivable from arguments or a finite kind enum (logs, resource details, Istio config read/write, metrics/traces namespace gate, traffic graph). On OpenShift Container Platform, resource/graph declarations also include deploymentconfigs and routes from the operator’s viewer role.
   • Unbounded for mesh-wide status and mesh cluster listing, where Kiali aggregates control-plane and observability backends that cannot be expressed as a finite Kubernetes requirement set.

4. Optional: Set up multi-cluster support.

   Kiali can manage multiple clusters within an Istio service mesh. Most Kiali tools accept an optional meshCluster parameter to target a specific mesh cluster. When a tool does not name a cluster, Kiali uses the home cluster, which is the cluster where Kiali runs.

   To discover available mesh cluster names before calling other tools, use ossm_list_mesh_clusters. The name field from that response is the only valid value for meshCluster.

   ossm tools do not take an OpenShift context. Use the mesh cluster name from ossm_list_mesh_clusters. Core tools on the same MCP server still use context when multi-cluster mode is enabled.