AI assistants like Claude can help manage ROSA HCP clusters at every level — from provisioning clusters through OCM to troubleshooting workloads inside the cluster. This guide covers three complementary approaches and helps you choose the right one for your use case.

Choosing Your Approach

There is no single “right” tool — each approach adds value in different scenarios:

The rest of this guide walks through each approach in detail.

Part 1: ROSA MCP Server — OCM Cluster Lifecycle

The ROSA MCP Server is a Model Context Protocol (MCP) server that enables AI assistants to manage ROSA HCP clusters through the OpenShift Cluster Manager (OCM) API. It currently exposes six tools — cluster listing, cluster details, cluster creation, identity provider setup, authentication status, and a prerequisites guide — through the open MCP standard.

When to use the ROSA MCP Server over the CLI

• Non-CLI environments — Web portals, chat interfaces, or AI tools without shell access (e.g., Claude on claude.ai)
• Structured JSON output — Cleaner than parsing CLI text tables, less room for the AI to misread output
• The prerequisites guide — The most unique tool: it injects verified domain knowledge (IAM roles, OIDC configs, operator role setup) so the AI doesn’t have to guess. This knowledge isn’t available from rosa --help
• Future: policy guardrails — An MCP server can enforce organizational policies (“always encrypt”, “require cost-center tag”) that raw CLI access cannot

Prerequisites

• A ROSA HCP cluster in ready state
• rosa CLI installed and logged in (rosa login)
• ocm CLI installed and logged in (ocm login)
• oc CLI logged in to your cluster
• helm CLI installed
• One of the following for OCM authentication:
  • An OCM service account with client credentials (client ID + client secret) from console.redhat.com/iam/service-accounts — recommended
  • An OCM offline token from console.redhat.com/openshift/token
• Claude Code installed

Architecture Overview

The ROSA MCP Server acts as a bridge between AI assistants and the OpenShift Cluster Manager (OCM) API:

Available Tools

Transport Modes

The server supports two transport modes with different authentication models:

• stdio — For local, single-user usage. The server reads JSON-RPC messages from stdin and writes responses to stdout. Authentication uses environment variables (OCM_CLIENT_ID + OCM_CLIENT_SECRET for service accounts, or OCM_OFFLINE_TOKEN for user tokens), meaning a single identity is baked into the process for its lifetime.
• SSE (Server-Sent Events) — For remote, multi-user usage. The server exposes HTTP endpoints (/sse for the event stream, /message for requests). Authentication is per-request via HTTP headers, making it multi-tenant — each user authenticates independently, which is the right choice for shared platform portals.

Authentication Methods

The server supports three authentication methods, checked in priority order:

Set Environment Variables

Set the variables used throughout this guide:

Local vs. Cluster Deployment

This guide focuses on deploying to OpenShift for shared team access. For local development and testing, see the ROSA MCP Server README .

Deploy to OpenShift

The project includes an OpenShift template for production deployment. This creates a Deployment, Service, and Route with TLS termination:

1. Log in to your cluster

2. Create a project for the MCP server

3. Deploy using the template

   You can customize template parameters:

   Parameter	Default	Description
   IMAGE	quay.io/redhat-ai-tools/rosa-mcp-server	Container image
   IMAGE_TAG	latest	Image tag
   PORT	8080	SSE transport port
   MCP_HOST	rosa-mcp-server.example.com	Route hostname
   CERT_MANAGER_ISSUER_NAME	letsencrypt-dns	TLS certificate issuer (requires cert-manager)

   The CERT_MANAGER_ISSUER_NAME parameter requires cert-manager to be installed on the cluster. If cert-manager is not available, remove the cert-manager.io annotations from the Route in the template and configure TLS separately using your cluster’s certificate setup.

4. Verify the deployment

5. Test the deployed endpoint

   A 200 response confirms the SSE endpoint is reachable. Note that curl may return a non-zero exit code (18 or 28) because SSE connections stream indefinitely — this is expected behavior.

Configure Claude Code MCP Integration

Claude Code can connect to the deployed ROSA MCP Server, enabling you to manage ROSA clusters through natural language.

1. Get the Route URL for the deployed server

2. Get your OCM credentials — either service account client credentials (recommended) or an offline token:

   • Service account: Create one at console.redhat.com/iam/service-accounts . Note the client ID and client secret.
   • Offline token: Get one from console.redhat.com/openshift/token .

3. Create or update .claude/settings.local.json in your project directory

   Option A — Client credentials (recommended):

   Option B — Offline token:

   Replace ${CLUSTER_NAME} and ${CLUSTER_DOMAIN} with the values from the environment variables set earlier.

   The settings.local.json file contains your OCM credentials. This file is gitignored by default and should never be committed to version control.

4. Restart Claude Code to load the MCP server

5. Verify the connection by listing the registered MCP tools

   You should see the rosa-hcp server listed with six tools: whoami, get_clusters, get_cluster, create_rosa_hcp_cluster, get_rosa_hcp_prerequisites_guide, and setup_htpasswd_identity_provider.

   You can also type /mcp inside a Claude Code session to see connected MCP servers and their status.

Verify End-to-End

With the MCP server configured in Claude Code, test the integration with these example prompts:

The AI assistant will call the appropriate MCP tool and return formatted results directly in the conversation.

Troubleshooting

MCP Server Not Connecting

If Claude Code cannot connect to the deployed ROSA MCP Server:

1. Verify the pod is running:

2. Check the pod logs for errors:

3. Verify the Route is accessible:

   A 200 response confirms the SSE endpoint is reachable.

SSE: “Missing sessionId” Error

Cause: Sending a POST to /message without establishing an SSE session first. The SSE transport requires a two-step protocol:

1. GET /sse — receives a session ID via SSE event
2. POST /message?sessionId=<id> — sends requests using that session ID

This is handled automatically by MCP client libraries (Claude Code). Do not test the SSE endpoint manually with curl POST requests.

HTPasswd: Password Validation Errors

Solution: HTPasswd passwords must be at least 14 characters. The server uses ROSA CLI validation rules. Usernames cannot contain /, :, or % characters, and cluster-admin is a reserved username.

Token Expiration

If you see authentication failures, the OCM token in your settings.local.json may have expired.

Solution: Switch to OCM service account client credentials (X-OCM-CLIENT-ID + X-OCM-CLIENT-SECRET), which never expire — the SDK handles the OAuth2 token lifecycle automatically. Alternatively, OCM offline tokens (from console.redhat.com/openshift/token ) are long-lived and do not expire under normal use. If you are using a short-lived access token, replace it with either option for persistent setups.

Part 2: OpenShift MCP Server — In-Cluster Day 2 Operations

The OpenShift MCP Server is a Kubernetes-native MCP server that gives AI assistants direct, RBAC-enforced access to your cluster’s Kubernetes API. While the ROSA MCP Server handles OCM-level cluster lifecycle, this server handles what happens inside the cluster — the Day 2 operations where most troubleshooting time is spent.

Why This Matters

Most operational questions are about workloads, not fleet management: “Why is my pod crashing?”, “What’s consuming memory in this namespace?”, “Show me the last deploy’s events.” The OpenShift MCP Server exposes these capabilities through MCP tools without requiring users to learn oc or kubectl syntax.

Key Toolsets

How It Complements ROSA MCP

Deploy to OpenShift via Helm

The OpenShift MCP Server provides an OCI Helm chart for deployment. The chart creates a Deployment, ServiceAccount, RBAC bindings, Service, and Ingress/Route.

1. Create a namespace

   OpenShift restricts project names starting with kubernetes- or openshift-. Use a different name such as mcp-server-k8s.

2. Deploy with Helm

   The ${CLUSTER_DOMAIN} variable was set in the environment variables step above.

   This deployment uses the built-in view ClusterRole, which grants read-only access to most cluster resources. For write access (e.g., scaling deployments, managing Helm releases), bind to the edit or admin ClusterRole instead. You can also add --set readOnly=true for defense-in-depth at the application level.

3. Verify the deployment

   The Helm chart generates the Route name with a random suffix (e.g., kubernetes-mcp-server-jh7zt). Use the namespace-scoped commands below to discover the actual Route URL.

4. Test the endpoint

   A 200 response confirms the SSE endpoint is available. Note that curl may return a non-zero exit code (18 or 28) because SSE connections stream indefinitely — this is expected behavior, not an error.

Configure Claude Code

1. Get the Route URL

2. Add the server to .claude/settings.local.json

   Replace the URL with the actual Route URL from step 1.

   The OpenShift MCP Server deployed in-cluster uses its ServiceAccount for authentication — no user token is needed in the Claude Code configuration. Access is governed by the RBAC bindings configured during Helm deployment.

3. Restart Claude Code and verify

   You should see the openshift server listed with tools for pods, deployments, logs, events, metrics, and Helm operations.

Example Prompts

With the OpenShift MCP Server connected, test the integration with these prompts:

Use both MCP servers together for full-stack AI-assisted management: ROSA MCP for provisioning and fleet operations, OpenShift MCP Server for Day 2 troubleshooting and workload visibility.

For full documentation and advanced configuration, see the OpenShift MCP Server repository .

Part 3: OpenShift Lightspeed — AI in the Console

OpenShift Lightspeed is an AI assistant embedded directly in the OpenShift web console. It provides contextual help to developers and administrators without leaving the console UI.

When to Use Lightspeed

Lightspeed is ideal for developers who work primarily in the OpenShift web console and want in-context AI assistance — explaining error messages, suggesting fixes, or answering “how do I” questions about the resource they’re currently viewing.

Connecting Lightspeed to Claude

Lightspeed supports Claude as its backing model through two providers:

• AWS Bedrock — Uses an IRSA-based proxy for authentication between the OpenShift cluster and the Bedrock API. See Configuring OpenShift Lightspeed with Claude via AWS Bedrock for the complete setup guide.
• Google Vertex AI — Officially supported integration. See the Red Hat documentation for configuring Vertex AI .

Comparison

Think of it this way: Lightspeed puts Claude inside the console; MCP servers put the cluster inside Claude. Lightspeed is best for console-first workflows. MCP servers are best for CLI-first or automation workflows where Claude orchestrates operations across multiple tools.

Cleanup

1. Remove the ROSA MCP Server deployment

2. Remove the OpenShift MCP Server deployment (if deployed)

3. Remove any test identity providers

4. Remove Claude Code MCP configuration

   Remove the rosa-hcp and openshift entries from .claude/settings.local.json.

Additional Resources

• ROSA MCP Server GitHub Repository
• OpenShift MCP Server GitHub Repository
• Configuring OpenShift Lightspeed with Claude via AWS Bedrock
• Model Context Protocol Specification
• Claude Code Documentation
• OCM API Documentation
• ROSA Documentation
• Red Hat AI on OpenShift — What’s New in 4.22
• MCP Gateway with Kuadrant Connectivity Link