OSDOCS-16078# MCP server for OCP (TP)

_topic_maps/_topic_map.yml

@@ -5015,3 +5015,15 @@ Topics:
 #  - Name: Collecting OKD Virtualization data for community report
 #    File: virt-collecting-virt-data
 #    Distros: openshift-origin
+---
+Name: AI applications
+Dir: ai_applications
+Distros: openshift-enterprise,openshift-origin,openshift-online
+Topics:
+- Name: MCP server
+  Dir: mcp_server
+  Distros: openshift-enterprise,openshift-origin
+  Topics:
+    - Name: MCP server overview
+      File: mcp-server-overview
+      Distros: openshift-enterprise,openshift-origin

ai_applications/_attributes

@@ -0,0 +1 @@
+../_attributes/

ai_applications/images

@@ -0,0 +1 @@
+../images/

ai_applications/mcp_server/_attributes

@@ -0,0 +1 @@
+../../_attributes/

ai_applications/mcp_server/images

@@ -0,0 +1 @@
+../images

ai_applications/mcp_server/mcp-server-overview.adoc

@@ -0,0 +1,45 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="mcp-server-overview"]
+= Inspect clusters with MCP server for Red Hat {product-title}
+include::_attributes/common-attributes.adoc[]
+:context: mcp-server-overview
+
+toc::[]
+
+[role="_abstract"]
+When a problem occurs on your {product-title} 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 {product-title} feature provides an AI tool for this purpose to quickly and easily diagnose your {product-title} cluster.
+
+:FeatureName: MCP server for Red Hat {product-title}
+include::snippets/technology-preview.adoc[]
+
+include::modules/ai-app-mcp-server-ai-safety.adoc[leveloffset=+1]
+
+include::modules/ai-app-mcp-server-model-context-protocol-overview.adoc[leveloffset=+1]
+
+include::modules/ai-app-mcp-server-mcp-server-overview.adoc[leveloffset=+1]
+
+include::modules/ai-app-mcp-server-mcp-gateway-overview.adoc[leveloffset=+1]
+
+include::modules/ai-app-mcp-server-prompting-workflow.adoc[leveloffset=+1]
+
+include::modules/ai-app-mcp-server-install.adoc[leveloffset=+1]
+
+include::modules/ai-app-mcp-server-install-helm.adoc[leveloffset=+2]
+
+include::modules/ai-app-mcp-server-connect-client.adoc[leveloffset=+2]
+
+include::modules/ai-app-mcp-server-install-gateway.adoc[leveloffset=+2]
+
+include::modules/ai-app-mcp-server-verify-deployment.adoc[leveloffset=+2]
+
+include::modules/ai-app-mcp-server-configure-gateway.adoc[leveloffset=+2]
+
+include::modules/ai-app-mcp-server-configure-rbac.adoc[leveloffset=+2]
+
+include::modules/ai-app-mcp-server-revoke-cr-access.adoc[leveloffset=+2]
+
+include::modules/ai-app-mcp-server-setup-authentication.adoc[leveloffset=+2]
+
+include::modules/ai-app-mcp-server-setup-authorization.adoc[leveloffset=+2]
+
+include::modules/ai-app-mcp-server-prompting-instructions.adoc[leveloffset=+1]

ai_applications/mcp_server/modules

@@ -0,0 +1 @@
+../../modules/

ai_applications/mcp_server/snippets

@@ -0,0 +1 @@
+../../snippets

ai_applications/modules

@@ -0,0 +1 @@
+../modules/

ai_applications/snippets

@@ -0,0 +1 @@
+../snippets/

modules/ai-app-mcp-server-ai-safety.adoc

@@ -0,0 +1,96 @@
+// Module included in the following assemblies:
+//
+// * ai_applications/mcp_server/mcp-server-overview.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ai-app-mcp-server-ai-safety_{context}"]
+= AI safety
+
+// ???AI warning. Get legal blurb as an OCP snippet: https://docs.google.com/document/d/1eVk8pMiSTqjfQSwU_h21BBXJ5PN8jbSLcU0wBtUt7bs/edit?tab=t.0#heading=h.dyq1r89dkf3e???
+
+[role="_abstract"]
+When using MCP (Model Context Protocol) server for Red Hat {product-title}, it is advised that you adhere to the following AI safety processes and best practices.
+
+[id="ai-app-mcp-server-ai-safety-data-ownership_{context}"]
+== Data ownership
+The MCP server for Red Hat {product-title} 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 {product-title}: 
+
+* Cluster:k8s_mcp_tool_calls:sum: 
+
+* Total count of all 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.
+
+[id="ai-app-mcp-server-ai-safety-hitl_{context}"]
+== 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.
+
+[id="ai-app-mcp-server-ai-safety-privacy-redaction_{context}"]
+== Data privacy and redaction
+The MCP server for Red Hat {product-title} 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 as an MCP gateway extension to monitor and sanitize outgoing payloads. For how to scope and limit MCP access to specific CRs, see Section _Revoke access to Custom Resources_.
+
+[id="ai-app-mcp-server-ai-safety-audit-trail_{context}"]
+== Audit trail recommendation
+The MCP server for Red Hat {product-title} 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 Section _Install MCP server for Red Hat {product-title}_.
+
+[id="ai-app-mcp-server-ai-safety-mcp-servers-hitl_{context}"]
+== 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 {product-title}.
+
+[id="ai-app-mcp-server-ai-safety-governance-guardrails_{context}"]
+== 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.
++
+disabled_tools = ["resources_delete", "pods_delete"]. Disable destructive tool calls in `config.toml`.
+
+* *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:
++
+[source,terminal]
+----
+$ helm uninstall openshift-mcp-server
+----
+
+* *RBAC revocation*:
++
+Remove the user's rolebinding or clusterrolebinding. For more information, see Section _Install MCP server for Red Hat {product-title}_.
+
+* *Remove access through the MCP gateway*
++
+To remove access through the gateway, you can delete the MCPServerRegistration CR by running the following command:
++
+[source,terminal]
+----
+$ oc delete mcpsr <name of registration>
+----

modules/ai-app-mcp-server-configure-gateway.adoc

@@ -0,0 +1,162 @@
+// Module included in the following assemblies:
+//
+// * ai_applications/mcp_server/mcp-server-overview.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ai-app-mcp-server-configure-gateway_{context}"]
+= Configure the MCP gateway
+
+[role="_abstract"]
+To install the Model Context Protocol (MCP) server for Red Hat {product-title} feature, configure the MCP gateway by creating HTTPRoute and MCPServerRegistration resources.
+
+.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
+
+. Create the HTTPRoute for the MCP server by running the following command:
++
+[source,terminal]
+----
+$ 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-system
+    sectionName: mcp
+  hostnames:
+  - ${MCP_SERVER_HOST}
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /mcp
+    backendRefs:
+    - name: openshift-mcp-server
+      port: 8080
+EOF
+----
++
+Where `${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:
++
+[source,terminal]
+----
+$ oc apply -f - <<EOF
+apiVersion: mcpserverregistrations.mcp.kuadrant.io
+kind: MCPServerRegistration
+metadata:
+  name: my-mcp-server-reg
+  namespace: openshift-mcp-server
+spec:
+  toolPrefix: "myserver_"
+  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:
++
+[source,terminal]
+----
+$ oc wait --for=condition=Ready mcpsr/my-mcp-server-reg -n openshift-mcp-server --timeout=120s
+$ oc get mcpsr -A
+----
++
+.Example
++
+[source,terminal]
+----
+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:
++
+[source,terminal]
+----
+$ oc describe mcpsr my-mcp-server-reg -n openshift-mcp-server
+----
+
+. Check the controller logs by running the following command:
++
+[source,terminal]
+----
+$ oc logs -n openshift-mcp-server deployment/mcp-gateway-controller
+----
+
+. Check the broker logs for tool discovery by running the following command:
++
+[source,terminal]
+----
+$ oc logs -n openshift-mcp-server deployment/mcp-gateway-broker-router
+----
+
+. 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:
++
+[source,terminal]
+----
+$ 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"}}}'
+----
++
+Where <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:
++
+[source,terminal]
+----
+$ 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:
++
+[source,terminal]
+----
+$ 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"}'
+----
++
+Where <cluster-name>.<domain-name> is the name and domain of your cluster.
+
+.. Clean up by running the following command:
++
+[source,terminal]
+----
+$ rm -f /tmp/mcp_headers
+----
++
+You should now see your MCP server tools in the response, prefixed with your configured toolPrefix (for example, myserver_).