From ca89088a6e339063c96bc23d862566179a237000 Mon Sep 17 00:00:00 2001 From: Lisa Pettyjohn Date: Fri, 3 Apr 2026 10:24:06 -0400 Subject: [PATCH] MCP_Server --- _topic_maps/_topic_map.yml | 12 ++ ai_applications/_attributes | 1 + ai_applications/images | 1 + ai_applications/mcp_server/_attributes | 1 + ai_applications/mcp_server/images | 1 + .../mcp_server/mcp-server-overview.adoc | 45 ++++ ai_applications/mcp_server/modules | 1 + ai_applications/mcp_server/snippets | 1 + ai_applications/modules | 1 + ai_applications/snippets | 1 + modules/ai-app-mcp-server-ai-safety.adoc | 96 +++++++++ .../ai-app-mcp-server-configure-gateway.adoc | 162 ++++++++++++++ modules/ai-app-mcp-server-configure-rbac.adoc | 59 ++++++ modules/ai-app-mcp-server-connect-client.adoc | 39 ++++ .../ai-app-mcp-server-install-gateway.adoc | 24 +++ modules/ai-app-mcp-server-install-helm.adoc | 49 +++++ modules/ai-app-mcp-server-install.adoc | 31 +++ ...i-app-mcp-server-mcp-gateway-overview.adoc | 31 +++ ...ai-app-mcp-server-mcp-server-overview.adoc | 28 +++ ...erver-model-context-protocol-overview.adoc | 20 ++ modules/ai-app-mcp-server-overview.adoc | 11 + ...app-mcp-server-prompting-instructions.adoc | 182 ++++++++++++++++ .../ai-app-mcp-server-prompting-workflow.adoc | 22 ++ .../ai-app-mcp-server-revoke-cr-access.adoc | 56 +++++ ...i-app-mcp-server-setup-authentication.adoc | 198 ++++++++++++++++++ ...ai-app-mcp-server-setup-authorization.adoc | 161 ++++++++++++++ .../ai-app-mcp-server-verify-deployment.adoc | 62 ++++++ 27 files changed, 1296 insertions(+) create mode 120000 ai_applications/_attributes create mode 120000 ai_applications/images create mode 120000 ai_applications/mcp_server/_attributes create mode 120000 ai_applications/mcp_server/images create mode 100644 ai_applications/mcp_server/mcp-server-overview.adoc create mode 120000 ai_applications/mcp_server/modules create mode 120000 ai_applications/mcp_server/snippets create mode 120000 ai_applications/modules create mode 120000 ai_applications/snippets create mode 100644 modules/ai-app-mcp-server-ai-safety.adoc create mode 100644 modules/ai-app-mcp-server-configure-gateway.adoc create mode 100644 modules/ai-app-mcp-server-configure-rbac.adoc create mode 100644 modules/ai-app-mcp-server-connect-client.adoc create mode 100644 modules/ai-app-mcp-server-install-gateway.adoc create mode 100644 modules/ai-app-mcp-server-install-helm.adoc create mode 100644 modules/ai-app-mcp-server-install.adoc create mode 100644 modules/ai-app-mcp-server-mcp-gateway-overview.adoc create mode 100644 modules/ai-app-mcp-server-mcp-server-overview.adoc create mode 100644 modules/ai-app-mcp-server-model-context-protocol-overview.adoc create mode 100644 modules/ai-app-mcp-server-overview.adoc create mode 100644 modules/ai-app-mcp-server-prompting-instructions.adoc create mode 100644 modules/ai-app-mcp-server-prompting-workflow.adoc create mode 100644 modules/ai-app-mcp-server-revoke-cr-access.adoc create mode 100644 modules/ai-app-mcp-server-setup-authentication.adoc create mode 100644 modules/ai-app-mcp-server-setup-authorization.adoc create mode 100644 modules/ai-app-mcp-server-verify-deployment.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index b7be255968b5..5aea86ac75c6 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 diff --git a/ai_applications/_attributes b/ai_applications/_attributes new file mode 120000 index 000000000000..f27fd275ea6b --- /dev/null +++ b/ai_applications/_attributes @@ -0,0 +1 @@ +../_attributes/ \ No newline at end of file diff --git a/ai_applications/images b/ai_applications/images new file mode 120000 index 000000000000..e4c5bd02a10a --- /dev/null +++ b/ai_applications/images @@ -0,0 +1 @@ +../images/ \ No newline at end of file diff --git a/ai_applications/mcp_server/_attributes b/ai_applications/mcp_server/_attributes new file mode 120000 index 000000000000..20cc1dcb77bf --- /dev/null +++ b/ai_applications/mcp_server/_attributes @@ -0,0 +1 @@ +../../_attributes/ \ No newline at end of file diff --git a/ai_applications/mcp_server/images b/ai_applications/mcp_server/images new file mode 120000 index 000000000000..5e67573196d8 --- /dev/null +++ b/ai_applications/mcp_server/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/ai_applications/mcp_server/mcp-server-overview.adoc b/ai_applications/mcp_server/mcp-server-overview.adoc new file mode 100644 index 000000000000..ce96d3b4e999 --- /dev/null +++ b/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] diff --git a/ai_applications/mcp_server/modules b/ai_applications/mcp_server/modules new file mode 120000 index 000000000000..36719b9de743 --- /dev/null +++ b/ai_applications/mcp_server/modules @@ -0,0 +1 @@ +../../modules/ \ No newline at end of file diff --git a/ai_applications/mcp_server/snippets b/ai_applications/mcp_server/snippets new file mode 120000 index 000000000000..7bf6da9a51d0 --- /dev/null +++ b/ai_applications/mcp_server/snippets @@ -0,0 +1 @@ +../../snippets \ No newline at end of file diff --git a/ai_applications/modules b/ai_applications/modules new file mode 120000 index 000000000000..43aab75b53c9 --- /dev/null +++ b/ai_applications/modules @@ -0,0 +1 @@ +../modules/ \ No newline at end of file diff --git a/ai_applications/snippets b/ai_applications/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/ai_applications/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/modules/ai-app-mcp-server-ai-safety.adoc b/modules/ai-app-mcp-server-ai-safety.adoc new file mode 100644 index 000000000000..9d3685f8c9c8 --- /dev/null +++ b/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 +---- \ No newline at end of file diff --git a/modules/ai-app-mcp-server-configure-gateway.adoc b/modules/ai-app-mcp-server-configure-gateway.adoc new file mode 100644 index 000000000000..16d6d3ca6672 --- /dev/null +++ b/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 - <.: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 . 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..:8001/mcp \ + -H "Content-Type: application/json" \ + -H "mcp-session-id: $SESSION_ID" \ + -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' +---- ++ +Where . 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_). diff --git a/modules/ai-app-mcp-server-configure-rbac.adoc b/modules/ai-app-mcp-server-configure-rbac.adoc new file mode 100644 index 000000000000..99c9045c49e4 --- /dev/null +++ b/modules/ai-app-mcp-server-configure-rbac.adoc @@ -0,0 +1,59 @@ +// 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-rbac_{context}"] += Configure RBAC enforcement + +[role="_abstract"] +To install the Model Context Protocol (MCP) server for Red Hat {product-title} feature, configure role-based access control (RBAC) to control access to cluster resources through the MCP server. 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 +[source,yaml] +---- +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 +---- diff --git a/modules/ai-app-mcp-server-connect-client.adoc b/modules/ai-app-mcp-server-connect-client.adoc new file mode 100644 index 000000000000..51ae061555f8 --- /dev/null +++ b/modules/ai-app-mcp-server-connect-client.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ai-app-mcp-server-connect-client_{context}"] += Connect a client to the MCP server + +[role="_abstract"] +To install the Model Context Protocol (MCP) server for Red Hat {product-title} feature, connect an MCP-compatible client, such as Claude Code, to the MCP server. + +.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 ++ +[source,json] +---- +{ + "mcpServers": { + "openshift": { + "type": "http", + "url": "/mcp" + } + } +} +---- ++ +Where `` is the hostname you configured during Helm installation. + +. Accept the CA certificate when prompted by the client. diff --git a/modules/ai-app-mcp-server-install-gateway.adoc b/modules/ai-app-mcp-server-install-gateway.adoc new file mode 100644 index 000000000000..8c9c7f3a9cdd --- /dev/null +++ b/modules/ai-app-mcp-server-install-gateway.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ai-app-mcp-server-install-gateway_{context}"] += Install the MCP gateway + +[role="_abstract"] +To install the Model Context Protocol (MCP) server for Red Hat {product-title} feature, install the MCP gateway to route traffic through security guardrails and authorization features. + +.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 the _Red Hat Connectivity Link_ documentation, Section _Installing the MCP gateway_. ++ +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. diff --git a/modules/ai-app-mcp-server-install-helm.adoc b/modules/ai-app-mcp-server-install-helm.adoc new file mode 100644 index 000000000000..f1bd5b4cbb67 --- /dev/null +++ b/modules/ai-app-mcp-server-install-helm.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ai-app-mcp-server-install-helm_{context}"] += Install the MCP server Helm chart + +[role="_abstract"] +To install the Model Context Protocol (MCP) server for Red Hat {product-title} feature, install the MCP server for Red Hat {product-title} Helm chart. + +.Prerequisites + +* Access to OpenShift console with admin rights. + +.Procedure + +. Install the MCP server for Red Hat {product-title} Helm chart by running the following command: ++ +[source,terminal] +---- +$ helm repo add openshift-helm-charts https://charts.openshift.io/ +---- ++ +[source,terminal] +---- +$ helm upgrade -i -n openshift-mcp-server --create-namespace openshift-mcp-server \ + openshift-helm-charts/redhat-openshift-mcp-server \ + --set config.toolsets={core,helm,kubevirt} \ + --set ingress.host= +---- ++ +Where `` is a fully qualified domain name (FQDN) that serves as the entry point for the {product-title} MCP server. 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`. + +.Verification + +The command returns output similar to the following: + +.Example +[source,terminal] +---- +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 +---- diff --git a/modules/ai-app-mcp-server-install.adoc b/modules/ai-app-mcp-server-install.adoc new file mode 100644 index 000000000000..fa6ea0f5c3dd --- /dev/null +++ b/modules/ai-app-mcp-server-install.adoc @@ -0,0 +1,31 @@ +:_mod-docs-content-type: PROCEDURE +[id="ai-mcp-server-install_{context}"] += Install MCP server for Red Hat {product-title} + +[role="_abstract"] +To install the Model Context Protocol (MCP) server for Red Hat {product-title} 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 {product-title} Helm chart. + +. Connect an MCP-compatible 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. \ No newline at end of file diff --git a/modules/ai-app-mcp-server-mcp-gateway-overview.adoc b/modules/ai-app-mcp-server-mcp-gateway-overview.adoc new file mode 100644 index 000000000000..898081c81ea4 --- /dev/null +++ b/modules/ai-app-mcp-server-mcp-gateway-overview.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: CONCEPT +[id="ai-app-mcp-server-mcp-gateway-overview_{context}"] += MCP gateway overview + +[role="_abstract"] +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. + diff --git a/modules/ai-app-mcp-server-mcp-server-overview.adoc b/modules/ai-app-mcp-server-mcp-server-overview.adoc new file mode 100644 index 000000000000..8b264e111478 --- /dev/null +++ b/modules/ai-app-mcp-server-mcp-server-overview.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: CONCEPT +[id="ai-app-mcp-server-mcp-server-overview_{context}"] += MCP server overview + +[role="_abstract"] +In the Model Context Protocol (MCP) ecosystem, the server's goal is to turn a specific data source or service into something an AI can understand and use. + +== 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 runs the Python script, queries the database, or calls the 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. diff --git a/modules/ai-app-mcp-server-model-context-protocol-overview.adoc b/modules/ai-app-mcp-server-model-context-protocol-overview.adoc new file mode 100644 index 000000000000..ff9a04b8d915 --- /dev/null +++ b/modules/ai-app-mcp-server-model-context-protocol-overview.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: CONCEPT +[id="ai-app-mcp-server-model-context-protocol-overview_{context}"] += Model Context Protocol overview + +[role="_abstract"] +MCP (Model Context Protocol) 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. diff --git a/modules/ai-app-mcp-server-overview.adoc b/modules/ai-app-mcp-server-overview.adoc new file mode 100644 index 000000000000..2f5172738881 --- /dev/null +++ b/modules/ai-app-mcp-server-overview.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: CONCEPT +[id="ai-app-mcp-server-overview_{context}"] += MCP server on {product-title} overview + +[role="_abstract"] +When there is a problem 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. + diff --git a/modules/ai-app-mcp-server-prompting-instructions.adoc b/modules/ai-app-mcp-server-prompting-instructions.adoc new file mode 100644 index 000000000000..924cd7b96fb4 --- /dev/null +++ b/modules/ai-app-mcp-server-prompting-instructions.adoc @@ -0,0 +1,182 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: CONCEPT +[id="ai-app-mcp-server-overview-prompting-instructions_{context}"] += MCP server for Red Hat {product-title} prompting + +[role="_abstract"] +With MCP server for {product-title} installed, you can now prompt the Large Language Model (LLM) to learn more about your cluster. + +// ???AI warning. Get legal blurb as an OCP snippet: https://docs.google.com/document/d/1eVk8pMiSTqjfQSwU_h21BBXJ5PN8jbSLcU0wBtUt7bs/edit?tab=t.0#heading=h.dyq1r89dkf3e??? + +[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 +[source,terminal] +---- +[[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 +[cols="1,1", options="header"] +|=== +2+| 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 + +2+| Argument Fields +| name (required) | Argument identifier +| description (optional) | Explanation of the argument's purpose +| required (optional) | Whether the argument must be provided (default: false) + +2+| Argument Substitution +2+| 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 {product-title} 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: + +[source,terminal] +---- +Check the health of my cluster +---- + +Or with specific parameters: +[source,terminal] +---- +Check the health of namespace production +---- + +You can also skip event checking for faster results: + +[source,terminal] +---- +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 +Toolsets can provide built-in prompts by implementing the GetPrompts() method. This allows toolset developers to ship workflow templates alongside their tools. + +.Example toolset prompts file +[source,go] +---- +func (t *MyToolset) GetPrompts() []api.ServerPrompt { + return []api.ServerPrompt{ + { + Prompt: api.Prompt{ + Name: "my-workflow", + Description: "Custom workflow for my toolset", + Arguments: []api.PromptArgument{ + { + Name: "namespace", + Description: "Target namespace", + Required: true, + }, + }, + }, + Handler: func(params api.PromptHandlerParams) (*api.PromptCallResult, error) { + args := params.GetArguments() + namespace := args["namespace"] + + // Build messages dynamically based on arguments + messages := []api.PromptMessage{ + { + Role: "user", + Content: api.PromptContent{ + Type: "text", + Text: fmt.Sprintf("Help me with namespace: %s", namespace), + }, + }, + } + + return api.NewPromptCallResult("Workflow description", messages, nil), nil + }, + }, + } +} +---- + +== 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. diff --git a/modules/ai-app-mcp-server-prompting-workflow.adoc b/modules/ai-app-mcp-server-prompting-workflow.adoc new file mode 100644 index 000000000000..c383a1ad338c --- /dev/null +++ b/modules/ai-app-mcp-server-prompting-workflow.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: CONCEPT +[id="ai-app-mcp-server-model-context-prompting-workflow_{context}"] += MCP server for Red Hat {product-title} Prompting workflow + +[role="_abstract"] +Prompting in the Model Context Protocol (MCP) server for {product-title} follows a specific workflow. + +When you prompt a Large Language Model (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. \ No newline at end of file diff --git a/modules/ai-app-mcp-server-revoke-cr-access.adoc b/modules/ai-app-mcp-server-revoke-cr-access.adoc new file mode 100644 index 000000000000..60fc4b5005a4 --- /dev/null +++ b/modules/ai-app-mcp-server-revoke-cr-access.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ai-app-mcp-server-revoke-cr-access_{context}"] += Revoke access to Custom Resources + +[role="_abstract"] +To install the Model Context Protocol (MCP) server for Red Hat {product-title} feature, revoke access to specific Custom Resource (CR) level resources to enhance security. It is highly recommended that you limit access to Secrets, ConfigMaps, and RBAC resources (RoleBindings, ClusterRoles). + +.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 +[source,yaml] +---- +# Deny access to Secrets +[[denied_resources]] +group = "" +version = "v1" +kind = "Secret" + +# 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" +---- diff --git a/modules/ai-app-mcp-server-setup-authentication.adoc b/modules/ai-app-mcp-server-setup-authentication.adoc new file mode 100644 index 000000000000..04835f56c2b7 --- /dev/null +++ b/modules/ai-app-mcp-server-setup-authentication.adoc @@ -0,0 +1,198 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ai-app-mcp-server-setup-authentication_{context}"] += Set up MCP gateway authentication + +[role="_abstract"] +To install the Model Context Protocol (MCP) server for Red Hat {product-title} feature, set up OAuth-based authentication for the MCP gateway, including OAuth discovery. + +.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: ++ +[source,terminal] +---- +$ oc set env deployment/mcp-gateway-broker-router -n openshift-mcp-server \ +OAUTH_RESOURCE_NAME="MCP Server" \ +OAUTH_RESOURCE="http://mcp.127-0-0-1.sslip.io:8001/mcp" \ +OAUTH_AUTHORIZATION_SERVERS="https://login.microsoftonline.com//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: ++ +[source,terminal] +---- +$ oc apply -f - </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: ++ +[source,terminal] +---- +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 ++ +[source,terminal] +---- +{ + "resource_name": "MCP Server", + "resource": "http://mcp.127-0-0-1.sslip.io:8001/mcp", + "authorization_servers": [ + "https://login.microsoftonline.com//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: ++ +[source,terminal] +---- +$ 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 ++ +[source,terminal] +---- +{ + "error": "Unauthorized", + "message": "Authentication required." +} +---- diff --git a/modules/ai-app-mcp-server-setup-authorization.adoc b/modules/ai-app-mcp-server-setup-authorization.adoc new file mode 100644 index 000000000000..68d181845d56 --- /dev/null +++ b/modules/ai-app-mcp-server-setup-authorization.adoc @@ -0,0 +1,161 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ai-app-mcp-server-setup-authorization_{context}"] += Set up MCP gateway authorization + +[role="_abstract"] +To install the Model Context Protocol (MCP) server for Red Hat {product-title} feature, set up tool-level authorization for the MCP gateway to control which users can access specific MCP tools. + +.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 +[source,json] +---- +{ + "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: ++ +[source,terminal] +---- +$ oc apply -f - </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..: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 +---- ++ +Where: + +* `spec.sectionName` targets the MCP server Listener. + +* `.` is the name and domain of your cluster. + +.Verification + +. Test that authorization now controls tool access by setting up the MCP Inspector: + +.. Start MCP Inspector (requires Node.js/npm) by running the following command: ++ +[source,terminal] +---- +$ npx @modelcontextprotocol/inspector@latest & +INSPECTOR_PID=$! +---- + +.. Wait for services to start by running the following command: ++ +[source,terminal] +---- +$ sleep 3 +---- + +.. Open MCP Inspector by going to the following URL: http://localhost:6274/?transport=streamable-http&serverUrl=http://mcp-gateway.apps..:8001/mcp. ++ +Where . is the name and domain of your cluster. + +. To stop the services later, run the following command: ++ +[source,terminal] +---- +$ 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: + +.. Check the AuthPolicy status by running the following command: ++ +[source,terminal] +---- +$ oc get authpolicy -A +---- +.. View the authorization logs by running the following command: ++ +[source,terminal] +---- +$ oc logs -n kuadrant-system -l authorino-resource=authorino +---- diff --git a/modules/ai-app-mcp-server-verify-deployment.adoc b/modules/ai-app-mcp-server-verify-deployment.adoc new file mode 100644 index 000000000000..e7c70a23cb77 --- /dev/null +++ b/modules/ai-app-mcp-server-verify-deployment.adoc @@ -0,0 +1,62 @@ +// Module included in the following assemblies: +// +// * ai_applications/mcp_server/mcp-server-overview.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ai-app-mcp-server-verify-deployment_{context}"] += Verify the MCP gateway deployment + +[role="_abstract"] +To install the Model Context Protocol (MCP) server for Red Hat {product-title} feature, verify that the MCP gateway is deployed and running correctly. + +.Prerequisites + +* Access to OpenShift console with admin rights. +* 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: ++ +[source,terminal] +---- +$ oc get pods -n openshift-mcp-server -l "app.kubernetes.io/instance=mcp-gateway" +---- ++ +.Example +[source,terminal] +---- +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: ++ +[source,terminal] +---- +$ oc get mcpgatewayextension -A +---- ++ +.Example ++ +[source,terminal] +---- +NAMESPACE NAME READY AGE +openshift-mcp-server mcp-gateway 105s +---- + +. Verify the broker-router deployment by running the following command: ++ +[source,terminal] +---- +$ oc logs -n openshift-mcp-server deployment/mcp-gateway-broker-router +---- + +. Verify EnvoyFilter was created in the gateway namespace by running the following command: ++ +[source,terminal] +---- +$ oc get envoyfilter -n openshift-mcp-server -l app.kubernetes.io/managed-by=mcp-gateway-controller +----