Inspect clusters with MCP server for Red Hat OpenShift

When problems occur on your OpenShift Container Platform cluster, you want to determine exactly what is happening, so that you can fix the issue as soon as possible. The MCP server for Red Hat OpenShift feature provides an AI tool to quickly and easily diagnose your OpenShift Container Platform cluster.

warning

MCP server for Red Hat OpenShift is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

AI safety

Because MCP server for Red Hat OpenShift grants AI agents access to cluster resources, you must follow safety practices to protect your cluster from unauthorized actions, data exposure, and prompt injection risks.

warning

This feature uses AI technology. Do not include any personal information or other sensitive information in your input. Interactions may be used to improve Red Hat’s products or services. Always review AI-generated content before using it.

Data ownership

The MCP server for Red Hat OpenShift does not store any information or state of the cluster. If you opt in, there are several telemetry metrics that are collected to understand the overall usage levels of the MCP server for Red Hat OpenShift:

Cluster:k8s_mcp_tool_calls:sum:
Total count of all Model Context Protocol (MCP) tool invocations across the cluster
Cluster:k8s_mcp_tool_errors:sum:
Total count of all failed MCP tool invocations across the cluster
Cluster:k8s_mcp_http_requests:sum:
Total count of all HTTP requests received by the MCP server

These metrics do not collect specific details of the calls, requests, or errors themselves; they only provide aggregate overall sums of the usage.

To opt in, edit TOML config:

[telemetry]
enabled = true

To opt out, edit TOML config:

[telemetry]
enabled = false

Required verification workflow: Human in the loop (HITL) enforcement

It is recommended that you assess the AI agent’s proposed action in the MCP client.
You should manually check suggested resource versions (for example, ensure the model is not suggesting deprecated APIs).
It is recommended that you use a human approval mechanism in the AI client interface for "write" actions.

Data privacy and redaction

The MCP server for Red Hat OpenShift has no internal mechanisms for PII and data redaction. To ensure that cluster information within allowed Custom Resources (CRs) complies with data privacy standards, deploy TrustyAI to monitor and sanitize outgoing payloads. For how to scope and limit MCP access to specific CRs, see "Revoke access to Custom Resources".

Audit trail recommendation

The MCP server for Red Hat OpenShift is configured to append a user-agent string in audit logs to identify that requests were made by an AI agent through the MCP server. Ensure that authorization is enabled via OAuth or MCP gateway. For more information, see "Install MCP server for Red Hat OpenShift".

Recommendations regarding 3rd-party MCP servers

For better security and control, it is recommended that third-party MCP hosts implement a HITL requirement to approve any "write" operations performed via the MCP server for Red Hat OpenShift.

AI governance and guardrails

MCP gateway acts as a centralized control point and enforces strict governance over agent-tool interactions through centralized authentication and identity management, using correctly scoped tokens and OAuth 2.0 to ensure agents only possess the specific permissions required for any given task. The MCP gateway further secures the environment using identity-based tool filtering, which removes unauthorized tools from the tools/list discovery process entirely, thus preventing agents from attempting to access forbidden capabilities.

To mitigate AI-specific risks, the gateway should be deployed with safety guardrails. Guardrails would include inspecting traffic payloads for prompt injections and safety violations by integrating with external engines like Trusty AI or NVIDIA Nemo. Additionally, the MCP gateway ensures operational stability and accountability by implementing rate limiting to prevent agent-driven denial-of-service attacks and providing comprehensive audit logging to track and analyze all tool usage.

Emergency removal of AI agent access

In an emergency, you can use any of the following possible actions to revoke access for the AI agent (via the MCP server):

Remove access to the offending tool in config.toml. Only enable specific tools:
```
enabled_tools = ["pods_list", "pods_get", "pods_log"]
```
Disable specific tools from enabled toolsets. Disable destructive tool calls in config.toml.
```
disabled_tools = ["resources_delete", "pods_delete"].
```
Create a production-safe configuration.
```
read_only = true
```
Allow writes, but prevent deletions.
```
disable_destructive = true
```
Uninstall the MCP server completely by running the following command:
```
$ helm uninstall openshift-mcp-server
```
RBAC revocation: Remove the user’s rolebinding or clusterrolebinding. For more information, see "Install MCP server for Red Hat OpenShift".
Remove access through the MCP gateway To remove access through the gateway, you can delete the MCPServerRegistration CR by running the following command:
```
$ oc delete mcpsr <name of registration>
```

Additional resources

Model Context Protocol overview

Model Context Protocol (MCP) is an open source standard that enables AI applications to securely connect to external data sources, tools, and workflows without custom integrations.

MCP is an open source standard for connecting AI applications to external systems.

Using MCP, AI applications, such as Claude Code or Cursor, can connect to the following items, enabling them to access key information and perform tasks:

Data sources: for example, local files, databases
Tools: for example, search engines, calculators
Workflows: for example, specialized prompts

MCP works similarly to a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices, MCP provides a standardized way to connect AI applications to external systems.

MCP server overview

A Model Context Protocol (MCP) server exposes cluster data and operations to AI models in a structured, secure way, so that AI agents can diagnose and act on your cluster without needing direct access to APIs or databases.

The Goals of an MCP server

The primary goal of an MCP server is to expose specific capabilities to an AI model in a structured, safe, and predictable way. Here are the key objectives an MCP server achieves:

Capability exposure: The server defines exactly what the AI is allowed to do or see. It does this by exposing three specific things:
- Tools: Executable functions that do things (for example, "Delete this file," "Post to Slack," or "Calculate mortgage").
- Resources: Read-only data sources that provide context (for example, "Read the contents of README.md" or "Fetch the logs from the last hour").
- Prompts: Predefined templates that guide the AI model’s behavior (for example, a "Code Reviewer" prompt that tells the AI exactly how to look for bugs in a specific language).
Abstraction of complexity: An MCP server hides the complicated parts of an integration. The LLM does not need to know how to write a SQL query or use a specific GitHub API. The server handles the code, the formatting, and the technical unique complexities, giving the LLM a clean, standardized result.
Execution and action: Unlike the MCP gateway, which just routes traffic, the server is where the logic lives. When an AI decides to use a tool, the MCP server is the component that actually executes using that tool. For example, runs a Python script, queries a database, or calls an external API.
Sandboxing and security: The server provides a layer of isolation. By running as a separate process, it can be restricted to only accessing specific folders or specific API endpoints. If the AI model attempts to undesired or unintended action, for example, tries to delete your entire hard drive, the server can deny the behavior based on its internal rules.

MCP gateway overview

The primary goal of a Model Context Protocol (MCP) gateway is to standardize and simplify how AI models interact with external data and tools. Without a gateway, an AI model would need a custom integration for every single database, API, or local file system it needs to access.

Aggregation and orchestration

A gateway connects to multiple MCP servers simultaneously. Instead of the LLM (Large Language Model) managing ten different connections, it communicates only with the gateway. The gateway then routes the LLM’s request to the specific server that holds the relevant information (for example, fetching Jira tickets from one server and Google Drive docs from another).

Security and access control

The gateway acts as a security perimeter.

It manages:

Authentication: Holding the API keys or tokens required for various servers.
Permissions: Ensuring the AI model only accesses the specific data or tools that the user authorized.
Privacy: Stripping sensitive information before it is sent back to the model provider.

Protocol translation

The gateway ensures that the communication between the AI model and the servers follows the MCP standard. It translates the high-level "intent" of the AI model into the specific JSON-RPC calls that the MCP servers understand.

Scalability

By decoupling the AI model from the data sources, you can add, remove, or update MCP servers without ever needing to change the core configuration of your AI application.

MCP server for Red Hat OpenShift Prompting workflow

By understanding the Model Context Protocol (MCP) prompting workflow you can better troubleshoot issues and optimize how your prompts reach cluster resources through the MCP server, gateway, and a Large Language Model (LLM).

When you prompt an LLM, the execution happens according to the following steps:

User types a prompt: "Are there any pods that keep restarting?".
MCP Host (for example, Claude Desktop): receives your prompt. It looks at its connected MCP servers and sees one has a tool called pods_list.
MCP gateway (If used): If you are in an enterprise environment, the Host talks to the gateway first. The gateway checks "Is this user allowed to access the cluster?" and "Is the cluster currently online?"
MCP server: The gateway (or Host) sends the command to the server. The server runs the actual code (the API call to OpenShift), gets the data, and sends it back.
LLM: Receives that raw data, "reads" it, and gives you the final summary.

Install MCP server for Red Hat OpenShift

Install and configure the MCP server for Red Hat OpenShift to enable AI agents to securely diagnose and inspect your cluster.

To install the MCP server for Red Hat OpenShift feature, complete the following procedures.

Prerequisites

Access to OpenShift console with admin rights.
Installed MCP-compatible client, such as Claude Code, Visual Studio Code (VS Code), Cursor, or OpenShift LightSpeed (OLS).

Procedure

Install the MCP server for Red Hat OpenShift Helm chart.
Connect a compatible with Model Context Protocol (MCP) client, such as Claude Code, to the MCP server.
Install the MCP gateway.
Verify the MCP gateway deployment.
Configure the MCP gateway.
Configure RBAC enforcement.
Revoke access to Custom Resources.
Set up the MCP gateway authentication.
Set up MCP gateway authorization.

Install the MCP server Helm chart

Install the Model Context Protocol (MCP) server Helm chart to deploy the MCP server for Red Hat OpenShift on your cluster, enabling AI agents to diagnose and inspect cluster resources.

Prerequisites

Access to OpenShift console with admin rights.

Procedure

Install the MCP server for Red Hat OpenShift Helm chart by running one of the following commands:

For read-only access (recommended for most use cases):

$ helm upgrade -i -n openshift-mcp-server --create-namespace openshift-mcp-server \
    openshift-helm-charts/redhat-openshift-mcp-server \
    --set config.toolsets=<toolset-names> \
    --set ingress.host=<hostname> \
    --set openshift=true \
    --set-json 'rbac.extraClusterRoleBindings=[{"name":"use-view-role","roleRef":{"name":"view","external":true}}]'

For full cluster access:

$ helm upgrade -i -n openshift-mcp-server --create-namespace openshift-mcp-server \
    openshift-helm-charts/redhat-openshift-mcp-server \
    --set config.toolsets=<toolset-names> \
    --set ingress.host=<hostname> \
    --set openshift=true \
    --set-json 'rbac.extraClusterRoleBindings=[{"name":"admin-access","roleRef":{"name":"cluster-admin","external":true}}]'

<hostname> is a fully qualified domain name (FQDN) that serves as the entry point for the MCP server for Red Hat OpenShift. This host address is used by the Ingress controller to route external traffic to the MCP server service. This should be a URL such as mcp-server.apps.cluster-name.domain.com.

<toolset-names> can include toolsets from the following table. Available toolsets

Toolset	Description	Default	Status
`core`	Most common tools for Kubernetes management (Pods, Generic Resources, Events, etc.)	Yes	Technology Preview
`config`	View and manage the current local Kubernetes configuration (kubeconfig)	Yes	Technology Preview
`netedge`	NetEdge troubleshooting tools for OpenShift Container Platform	No	Technology Preview
`helm`	Tools for managing Helm charts and releases	No	Technology Preview
`metrics`	Toolset for querying Prometheus and Alertmanager endpoints in efficient ways	No	Technology Preview
`ossm`	Most common tools for managing OSSM	No	Technology Preview
`kubevirt`	KubeVirt virtual machine management tools	No	Developer Preview
`tekton`	Tekton pipeline management tools for Pipelines, PipelineRuns, Tasks, and TaskRuns	No	Developer Preview

Verification

Check that the command returns output similar to the following:

Example output
Release "openshift-mcp-server" does not exist. Installing it now.
NAME: openshift-mcp-server
LAST DEPLOYED: Mon Apr 20 09:28:13 2026
NAMESPACE: openshift-mcp-server
STATUS: deployed
REVISION: 1
TEST SUITE: None

Connect a client to the MCP server

Connect a client that is compatible with the Model Context Protocol (MCP) to the MCP server so that an AI agent can interact with your cluster.

Prerequisites

Access to OpenShift console with admin rights.
The MCP server Helm chart is installed.

Procedure

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 route created in the Helm chart>/mcp"
    }
  }
}
```
  <url of the route created in the Helm chart> is the hostname you configured during Helm installation.
Accept the CA certificate when prompted by the client.

Install the MCP gateway

Install the Model Context Protocol (MCP) gateway to provide a secure, centralized entry point that enforces authentication, authorization, and rate limiting for all MCP server traffic.

Prerequisites

Access to OpenShift console with admin rights.
The MCP server Helm chart is installed.
MCP-compatible client connected.

Procedure

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.

Additional resources

Install the MCP gateway (Red Hat Connectivity Link)

Verify the MCP gateway deployment

Verify that the Model Context Protocol (MCP) gateway is deployed and running correctly before configuring routing, authentication, and authorization.

Prerequisites

Access to OpenShift Container Platform console with admin rights.
OpenShift CLI (oc) is installed.
The MCP server Helm chart is installed.
MCP-compatible client connected.
MCP gateway is installed.

Procedure

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
```

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

Verify the broker-router deployment by running the following command:
```
$ oc logs -n gateway-namespace deployment/mcp-gateway
```

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

Configure the MCP gateway

Configure the Model Context Protocol (MCP) gateway so that it can route client traffic to your MCP server and discover the tools the server exposes.

Prerequisites

Access to OpenShift console with admin rights.
The MCP server Helm chart is installed.
MCP-compatible client connected.
MCP gateway is installed and verified.

Procedure

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.

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 you configured during Helm installation.

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

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.

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

Check the controller logs by running the following command:

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

Check the broker logs for tool discovery by running the following command:
```
$ oc logs -n gateway-namespace deployment/mcp-gateway
```

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

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.

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"

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.

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

Configure RBAC enforcement

To control which cluster resources the Model Context Protocol (MCP) server can access, configure role-based access control (RBAC) so that AI agents are limited to only the resources they need.

By default, RBAC is enabled, and you can extend the ClusterRoles, ClusterRoleBindings, Roles, and Rolebindings.

Prerequisites

Access to OpenShift console with admin rights.
The MCP server Helm chart is installed.
MCP-compatible client connected.
MCP gateway is installed and verified.
The MCP gateway is configured.

Procedure

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
extraClusterRoles:
  - name: acm-managed-clusters
    rules:
      # Required for discovering and watching managed clusters
      - apiGroups: ["cluster.open-cluster-management.io"]
        resources: ["managedclusters"]
        verbs: ["list", "watch"]

# -- ClusterRoleBinding for the ACM managed clusters role
extraClusterRoleBindings:
  - name: acm-managed-clusters
    roleRef:
      name: acm-managed-clusters

# -- Role for accessing cluster-proxy-addon service in multicluster-engine namespace
extraRoles:
  - name: acm-cluster-proxy-discovery
    namespace: multicluster-engine
    rules:
      # Required for auto-discovering cluster-proxy-addon service
      - apiGroups: [""]
        resources: ["services"]
        verbs: ["get"]

# -- RoleBinding for the cluster-proxy-discovery role
extraRoleBindings:
  - name: acm-cluster-proxy-discovery
    namespace: multicluster-engine
    roleRef:
      name: acm-cluster-proxy-discovery

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

$ helm upgrade openshift-mcp-server openshift-helm-charts/redhat-openshift-mcp-server \
    -n openshift-mcp-server \
    -f rbac-values.yaml

Revoke access to Custom Resources

To prevent AI agents from reading or exposing confidential cluster data, you can revoke Model Context Protocol (MCP) server access to sensitive Custom Resources (CRs), such as Secrets and ConfigMaps, .

Prerequisites

Access to OpenShift console with admin rights.
The MCP server Helm chart is installed.
MCP-compatible client connected.
MCP gateway is installed and verified.
The MCP gateway is configured.
RBAC is configured.

Procedure

Configure denied resources to limit access to sensitive CRs. Use the following example file to revoke access to Secrets, ConfigMaps, and RBAC resources:

Example
# Deny access to Secrets
[[denied_resources]]
group = ""
version = "v1"
kind = "Secret"

# Deny access to ConfigMaps
[[denied_resources]]
group = ""
version = "v1"
kind = "ConfigMap"

# Deny access to RBAC resources for additional security
[[denied_resources]]
group = "rbac.authorization.k8s.io"
version = "v1"
kind = "Role"

[[denied_resources]]
group = "rbac.authorization.k8s.io"
version = "v1"
kind = "RoleBinding"

[[denied_resources]]
group = "rbac.authorization.k8s.io"
version = "v1"
kind = "ClusterRole"

[[denied_resources]]
group = "rbac.authorization.k8s.io"
version = "v1"
kind = "ClusterRoleBinding"

Apply this configuration by doing one of the following:

Save the configuration to a file (for example, deny-resources.toml) and pass it using a Helm values file:

$ helm upgrade openshift-mcp-server openshift-helm-charts/redhat-openshift-mcp-server \
    -n openshift-mcp-server \
    --set-file config.deniedResources=deny-resources.toml

Or use --set-json to pass the configuration inline:

$ helm upgrade openshift-mcp-server openshift-helm-charts/redhat-openshift-mcp-server \
    -n openshift-mcp-server \
    --set-json 'config.deniedResources=[{"group":"","version":"v1","kind":"Secret"},{"group":"","version":"v1","kind":"ConfigMap"}]'

Set up MCP gateway authentication

To ensure that only verified users can access MCP server for Red Hat OpenShift tools and cluster resources, set up OAuth-based authentication for the Model Context Protocol (MCP) gateway.

Prerequisites

Access to OpenShift console with admin rights.
The MCP server Helm chart is installed.
MCP-compatible client connected.
MCP gateway is installed and verified.
RBAC is configured.
You have revoked access to specific Custom Resources (CRs) as needed.
You have access to an Identity Provider (Entra ID).

Procedure

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="http://mcp.127-0-0-1.sslip.io:8001/mcp" \
OAUTH_AUTHORIZATION_SERVERS="https://login.microsoftonline.com/<tenant-id>/v2.0" \
OAUTH_BEARER_METHODS_SUPPORTED="header" \
OAUTH_SCOPES_SUPPORTED="openid,mcp-server,offline_access"

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

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.

Configure the Identity Provider (Entra ID) App Registration:
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".

Configure certificate trust for JWT validation by mounting the Entra ID CA certificate into the Authorino deployment by running the following commands:

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

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

This ensures that Authorino can verify JWT token signatures from Microsoft Entra ID.

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:
        'entra-id':
          jwt:
            issuerUrl: https://login.microsoftonline.com/<tenant-id>/v2.0
      response:
        unauthenticated:
          code: 401
          headers:
            'WWW-Authenticate':
              value: Bearer resource_metadata=http://mcp.127-0-0-1.sslip.io:8001/.well-known/oauth-protected-resource/mcp
          body:
            value: |
              {
                "error": "Unauthorized",
                "message": "Authentication required."
              }
EOF

Verification

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

curl http://mcp.127-0-0-1.sslip.io:8001/.well-known/oauth-protected-resource

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": [
    "openid",
    "mcp-server",
    "offline_access"
  ]
}

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

$ curl -v http://mcp.127-0-0-1.sslip.io:8001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

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

Additional resources

Microsoft Entra ID

Set up MCP gateway authorization

Set up tool-level authorization for the Model Context Protocol (MCP) gateway to control which users can access specific MCP server tools, ensuring that each user can only use the operations permitted by their role.

Prerequisites

Access to OpenShift console with admin rights.
The MCP server Helm chart is installed.
MCP-compatible client connected.
MCP gateway is installed and verified.
RBAC is configured.
You have revoked access to specific Custom Resources (CRs) as needed.
MCP gateway authentication is configured.
Your identity provider is configured to include group/role claims in JWT tokens.

Procedure

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.

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:
      'sso-server':
        jwt:
          issuerUrl: https://login.microsoftonline.com/<tenant-id>/v2.0
    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=http://mcp-gateway.apps.<cluster-name>.<domain-name>:8001/.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

spec.sectionName targets the MCP server Listener.
<cluster-name>.<domain-name> is the name and domain of your cluster.

Verification

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=http://mcp-gateway.apps..:8001/mcp. <cluster-name>.<domain-name> is the name and domain of your cluster.
To stop the services later, run the following command:
```
$ kill $INSPECTOR_PID
```
Authenticate using a user account configured with the required role claims in your identity provider.
Try the following allowed tools:
- pods_list
- events_list
- nodes_list
- deployments_get
Try this restricted tool: pods_delete Since this tool is restricted, you should get a 403 Forbidden error.
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
```

MCP server for Red Hat OpenShift prompting

Use Model Context Protocol (MCP) server prompts to query a Large Language Model (LLM) to identify and diagnose issues across your OpenShift Container Platform cluster.

note

To ensure that you get the best results when prompting be sure to:

Specify the namespace.
For Red Hat Advanced Cluster Management (ACM) for Kubernetes environments, specify the cluster.

MCP prompts

MCP Prompts are predefined templates that guide AI assistants through specific workflows.

They combine:

Structured guidance: Step-by-step instructions for common tasks
Parameterization: Arguments that customize the prompt for specific contexts
Conversation templates: Preformatted messages that guide the interaction

Creating custom prompts

Define custom prompts in your config.toml file. Code changes and recompilation are not needed.

Example custom prompts
[[prompts]]
name = "check-pod-logs"
title = "Check Pod Logs"
description = "Quick way to check pod logs"

[[prompts.arguments]]
name = "pod_name"
description = "Name of the pod"
required = true

[[prompts.arguments]]
name = "namespace"
description = "Namespace of the pod"
required = false

[[prompts.messages]]
role = "user"
content = "Show me the logs for pod {{pod_name}} in {{namespace}}"

[[prompts.messages]]
role = "assistant"
content = "I'll retrieve and analyze the logs for you."

Configuration reference

Prompt Fields
name (required)	Unique identifier for the prompt
title (optional)	Human-readable display name
description (required)	Brief explanation of what the prompt does
arguments (optional)	List of parameters the prompt accepts
messages (required)	Conversation template with role/content pairs
Argument Fields
name (required)	Argument identifier
description (optional)	Explanation of the argument's purpose
required (optional)	Whether the argument must be provided (default: false)
Argument Substitution
Use {{ argument_name}} placeholders in message content. The template engine replaces these with actual values when the prompt is called. If an optional argument is not provided, its placeholder is removed from the output.

Built-in prompts

The MCP server for Red Hat OpenShift includes several built-in prompts that are always available:

Cluster-health-check performs a comprehensive health assessment of your OpenShift cluster.

Arguments:

namespace (optional): Limit the health check to a specific namespace. Default: all namespaces.
check_events (optional): Include recent warning/error events in the analysis. Values: true or false. Default: true.

What it checks:

Nodes: Status and conditions (for example, Ready, MemoryPressure, DiskPressure)
Cluster Operators: Available and degraded status
Pods: Phase, container statuses, restart counts, and common issues (for example, CrashLoopBackOff, ImagePullBackOff)
Workload Controllers: Deployments, StatefulSets, and DaemonSets replica status
Persistent Volume Claims: Binding status
Events: Recent warning and error events from the last hour

Example usage:

Check the health of my cluster

Or with specific parameters:

Check the health of namespace production

You can also skip event checking for faster results:

Check the health of my cluster without events

The prompt gathers comprehensive diagnostic data and presents it to the LLM for analysis, which provides:

Overall health status (Healthy, Warning, or Critical)
Critical issues requiring immediate attention
Warnings and recommendations
Summary by component

Configuration file location

Place your prompts in the config.toml file used by the MCP server. Specify the config file path by using the --config flag when starting the server.

Toolset prompts

Some toolsets contain prompts and enabling the toolset enables the prompt(s).

Prompt merging

When both toolset and config prompts exist, config-defined prompts override toolset prompts with the same name. This allows administrators to customize built-in workflows. Prompts with unique names from both sources are available.

AI safety​

Data ownership​

Required verification workflow: Human in the loop (HITL) enforcement​

Data privacy and redaction​

Audit trail recommendation​

Recommendations regarding 3rd-party MCP servers​

AI governance and guardrails​

Emergency removal of AI agent access​

Model Context Protocol overview​

MCP server overview​

The Goals of an MCP server​

MCP gateway overview​

Aggregation and orchestration​

Security and access control​

Protocol translation​

Scalability​

MCP server for Red Hat OpenShift Prompting workflow​

Install MCP server for Red Hat OpenShift​

Install the MCP server Helm chart​

Connect a client to the MCP server​

Install the MCP gateway​

Verify the MCP gateway deployment​

Configure the MCP gateway​

Configure RBAC enforcement​

Revoke access to Custom Resources​

Set up MCP gateway authentication​

Set up MCP gateway authorization​

MCP server for Red Hat OpenShift prompting​

MCP prompts​

Creating custom prompts​

Built-in prompts​

Configuration file location​

Toolset prompts​

Prompt merging​

AI safety

Data ownership

Required verification workflow: Human in the loop (HITL) enforcement

Data privacy and redaction

Audit trail recommendation

Recommendations regarding 3rd-party MCP servers

AI governance and guardrails

Emergency removal of AI agent access

Model Context Protocol overview

MCP server overview

The Goals of an MCP server

MCP gateway overview

Aggregation and orchestration

Security and access control

Protocol translation

Scalability

MCP server for Red Hat OpenShift Prompting workflow

Install MCP server for Red Hat OpenShift

Install the MCP server Helm chart

Connect a client to the MCP server

Install the MCP gateway

Verify the MCP gateway deployment

Configure the MCP gateway

Configure RBAC enforcement

Revoke access to Custom Resources

Set up MCP gateway authentication

Set up MCP gateway authorization

MCP server for Red Hat OpenShift prompting

MCP prompts

Creating custom prompts

Built-in prompts

Configuration file location

Toolset prompts

Prompt merging