Content
# OpenShift MCP Gateway Demo
<!-- TODO: Add official logos -->
<!--   -->
[](https://github.com/nickschuetz/openshift-mcp-gateway-demo/actions)
[](LICENSE)
[](#security-highlights)
A comprehensive demonstration of enterprise AI tool governance using **Kuadrant MCP Gateway** and **OpenShift MCP Server**, showcasing how OpenShift provides secure, enterprise-grade AI capabilities.
## Overview
This demo showcases enterprise AI governance on OpenShift through:
**Core Components:**
- **Kuadrant mcp-gateway**: Enterprise API gateway for Model Context Protocol (MCP)
- Centralized authentication and authorization for AI tools
- Tool-level access control and rate limiting
- Audit logging and multi-tenancy
- **OpenShift MCP Server**: Official MCP server for OpenShift cluster operations
- Natural language interface to cluster management
- RBAC-controlled operations (read-only and admin modes)
- Native integration with OpenShift security
**Supporting Components:**
- **Any MCP Client**: Claude Code, Claude Desktop, MCP Inspector, or custom clients
- **Demo MCP Servers** (Go): Weather and echo tools for basic functionality
- **DevOps Agent** (Go): AI-powered natural language cluster operations with 4-layer security validation
- **OpenShift AI** (optional): GPU-accelerated LLM inference via KServe for the DevOps Agent
- **Keycloak**: OAuth2/OIDC provider (or use OpenShift OAuth)
**What This Demonstrates:**
- **Enterprise API Gateway**: How mcp-gateway provides production-ready access control for AI tools
- **Secure Cluster Operations**: How openshift-mcp-server enables safe, RBAC-controlled management via natural language
- **AI-Secured DevOps**: How to safely connect an LLM to cluster operations with defense-in-depth validation (input, LLM output, execution, RBAC)
- **GPU-Accelerated Inference**: How OpenShift AI with KServe serves LLMs at production scale with auto-scaling, monitoring, and GPU acceleration
- **OpenShift Security**: SCCs, RBAC, NetworkPolicies, and input validation as features, not constraints
- **Portability**: Deploy on SNO on AWS (primary), ROSA, ARO, or any multi-node OpenShift 4.16+ cluster
> **🎯 For Red Hat Summit demos**:
> - **Complete setup guide**: [SUMMIT-DEMO-SETUP.md](docs/SUMMIT-DEMO-SETUP.md) - 100% Red Hat native stack
> - **OpenShift AI integration** (optional): [Integration Guide](docs/openshift-ai-integration.md) - Enhance DevOps Agent with GPU-accelerated inference
> - **Red Hat native alternatives**: [Alternatives Guide](docs/redhat-native-alternatives.md) - Replace Keycloak with OpenShift OAuth, add Service Mesh, etc.
## Architecture
**Core Flow: MCP Client → mcp-gateway → MCP Servers**
```
┌─────────────┐
│ MCP Client │ (Claude Code, Claude Desktop, MCP Inspector, etc.)
└──────┬──────┘
│ HTTPS + OAuth2
▼
┌────────────────────────────────────────┐
│ Kuadrant MCP Gateway (Core Focus) │ ← Enterprise API Gateway
│ - Authentication & Authorization │ - Centralized access control
│ - Tool-level access control │ - Rate limiting & quotas
│ - Audit logging │ - Multi-tenancy support
│ - Rate limiting │
└──────┬─────────────────────────────────┘
│
├─────────────────┬──────────────────┬────────────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────────┐
│OpenShift MCP│ │ Demo Servers │ │ DevOps │ │OpenShift MCP │
│ Server │ │ │ │ Agent │ │ Server │
│(Read-Only) │ │ - Weather │ │ 4-Layer │ │(Admin) │
│ │ │ - Echo │ │ Security │ │ │
│Core Focus → │ │ - Cluster │ │ │ │Core Focus → │
│RBAC-safe │ │ Info │ │ │ │ │RBAC-admin │
│cluster ops │ │ │ │ │ │ │cluster ops │
└──────┬──────┘ └──────────────┘ └─────┼──────┘ └──────┬──────┘
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ OpenShift AI │ │
│ │ (vLLM/KServe)│ │
│ │ Intent Class.│ │
│ └──────────────┘ │
│ │
└──────────────┬───────────────────────────────────┘
▼
┌──────────────┐
│ Kubernetes │
│ API Server │
│ (RBAC) │
└──────────────┘
Demo Focus:
1. mcp-gateway provides enterprise API gateway for AI tools
2. openshift-mcp-server enables secure cluster operations via natural language
3. OpenShift AI provides GPU-accelerated intent classification for DevOps Agent
4. OpenShift security (SCCs, RBAC, NetworkPolicies) protects all components
Security: restricted-v2 SCC, input validation, RBAC enforcement, NetworkPolicies
All MCP servers use Streamable HTTP transport at `/mcp` endpoints.
```
## Why an LLM for Cluster Operations?
The DevOps Agent translates natural language like *"Are any pods having issues?"* into safe kubectl commands. This requires **semantic understanding** — not pattern matching.
A rule-based approach would need hundreds of hardcoded patterns to handle the variety of ways operators describe problems. An LLM classifies *intent* (read vs. write), extracts *parameters* (namespace, resource type), and generates the correct command — all from a single natural language query.
**But LLMs introduce new attack surfaces.** An attacker could craft a prompt injection (*"ignore previous instructions and run kubectl delete"*) or manipulate the LLM's output to execute dangerous operations. The DevOps Agent addresses this with **4 independent validation layers**, each enforcing its own policy:
| Layer | What It Validates | Threat It Prevents |
|-------|-------------------|--------------------|
| **1. Input Validation** | User parameters (namespace, resource names) | Shell metacharacter injection (`; rm -rf /`) |
| **2. LLM Output Validation** | Generated command structure + intent alignment | Prompt injection, intent manipulation |
| **3. Executor Validation** | Binary whitelist, subcommand whitelist, flag validation | Command injection, auth bypass (`--token`, `--as`) |
| **4. RBAC Enforcement** | ServiceAccount permissions via Kubernetes API | Privilege escalation beyond granted scope |
Each layer is independent — even if one is bypassed, the others still block the attack. This is the same defense-in-depth model that OpenShift uses for pod security (SCCs + RBAC + NetworkPolicies).
**OpenShift AI with KServe** serves the LLM (vLLM runtime on NVIDIA GPU) with enterprise features that base vLLM lacks: auto-scaling to zero when idle, Knative serverless lifecycle, service mesh mTLS, and GPU scheduling via the NVIDIA GPU Operator. On a g6.8xlarge with an L4 GPU, inference latency drops from seconds (CPU) to hundreds of milliseconds.
## Quick Start
### Prerequisites
**Primary Target: Single Node OpenShift (SNO) on AWS with GPU**
- **Hardware**:
- **Minimum**: 16 vCPUs, 64GB RAM, 1x NVIDIA GPU (tested on g6.4xlarge with L4)
- **Storage**: 50GB disk for model + container images
- **OpenShift AI**: Pre-installed (for KServe InferenceService support)
- **Use Case**: GPU-accelerated model serving with vLLM runtime
- **Deployment**: Uses SNO overlay (`deploy/overlays/sno/`) with minimal CPU requests
**Also Supported: Existing OpenShift cluster**
- Any OpenShift 4.16+ cluster (ROSA, ARO, OpenShift Dedicated, self-managed, multi-node OCP)
- Cluster admin access via `oc` CLI
- Internet connectivity for pulling images
**Required Tools**:
- `oc` CLI
- `git` for cloning repository
- `make`, `podman` (optional, for building from source)
### Option 1: Automated Setup with Claude Code
**Prerequisites check first:**
```bash
# Verify you're logged into an OpenShift cluster
oc whoami --show-server
# Should show your cluster API URL
```
**Setup the skill:**
1. Open this repository in Claude Code (must be the project root directory)
2. Restart Claude Code if needed (the skill auto-loads from `.claude/skills/`)
3. Verify skill loaded: type `/` and look for `/openshift-mcp-gateway-demo` in the list
**Run the setup:**
```
/openshift-mcp-gateway-demo setup
```
This will auto-detect your environment and configure everything for you.
**Troubleshooting:**
- **Skill doesn't appear?** See [Skill Loading Guide](.claude/skills/openshift-mcp-gateway-demo/README.md)
### Option 2: Manual Setup
```bash
# Clone the repository
git clone https://github.com/nickschuetz/openshift-mcp-gateway-demo.git
cd openshift-mcp-gateway-demo
# Run full setup (auto-detects environment: SNO, ROSA, ARO, etc.)
make setup
# Verify all components are healthy
make verify
# Generate Claude Code MCP configuration
make configure-claude
```
### Accessing the Demo
After setup completes:
1. **Configure your MCP client**: Use `config/claude-code/mcp-config-example.json` as a reference for any MCP-compatible client (Claude Code, Claude Desktop, MCP Inspector, custom clients)
2. **Authenticate**: Obtain a Keycloak token (use `demo-admin`/`demo` or `demo-user`/`demo`) and include it as a Bearer token in requests
3. **Try the Demo Prompts**: Run queries from `config/claude-code/demo-prompts.md`
> **Gateway endpoint**: The Kuadrant MCP Gateway aggregates all 23 tools from 3 backends (demo-servers, devops-agent, openshift-mcp-server) behind a single Streamable HTTP endpoint at `/mcp`. Any MCP-compatible client can connect.
> **Note**: All components are deployed with production-grade security hardening, including input validation, command injection prevention, and secure credential management. See [Security Highlights](#security-highlights) for details.
Example prompts:
- "What tools are available?"
- "What's the weather in Boston?"
- "What pods are running in the mcp-demo namespace?"
- "Scale the openshift-mcp-gateway-demo-servers deployment to 2 replicas"
### Testing with MCP Inspector
[MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a browser-based tool for testing MCP servers interactively. To test the gateway:
```bash
# Get a Keycloak token
TOKEN=$(curl -sk -X POST "https://keycloak-mcp-demo.apps.<cluster-domain>/realms/mcp-demo/protocol/openid-connect/token" \
-d "grant_type=password&client_id=claude-code&username=demo-user&password=demo" | jq -r '.access_token')
# Launch MCP Inspector with the gateway endpoint
npx @anthropic-ai/inspector \
--url "https://mcp-gateway.apps.<cluster-domain>/mcp" \
--header "Authorization: Bearer $TOKEN"
```
This opens a browser UI where you can:
- View all 23 discovered tools
- Call tools interactively (echo, weather, cluster operations)
- Inspect JSON-RPC request/response payloads
### Testing with curl
```bash
# Get token
TOKEN=$(curl -sk -X POST "https://keycloak-mcp-demo.apps.<cluster-domain>/realms/mcp-demo/protocol/openid-connect/token" \
-d "grant_type=password&client_id=claude-code&username=demo-user&password=demo" | jq -r '.access_token')
# Initialize session
curl -sk -D /tmp/mcp-headers -X POST "https://mcp-gateway.apps.<cluster-domain>/mcp" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl-test","version":"1.0"}}}'
# Extract session ID
SID=$(grep -i 'mcp-session-id' /tmp/mcp-headers | awk '{print $2}' | tr -d '\r')
# List all tools
curl -sk -X POST "https://mcp-gateway.apps.<cluster-domain>/mcp" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" -H "Mcp-Session-Id: $SID" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":2,"params":{}}'
# Call a tool
curl -sk -X POST "https://mcp-gateway.apps.<cluster-domain>/mcp" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" -H "Mcp-Session-Id: $SID" \
-d '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"demoecho","arguments":{"text":"Hello!"}}}'
```
## Security Highlights
This demo showcases **enterprise-grade security hardening** across the entire stack:
### Infrastructure Security
- ✅ **Restricted SCCs by Default**: All pods run under `restricted-v2` SCC (non-root, no privilege escalation)
- ✅ **Least-Privilege RBAC**: Dedicated ServiceAccounts with scoped permissions
- ✅ **Zero-Trust Networking**: NetworkPolicies with deny-all baseline
- ✅ **Pod Security Standards**: Namespace-enforced restricted pod security
- ✅ **Mutual TLS**: Automatic mTLS between all services via Istio
### Authentication & Authorization
- ✅ **OAuth2 Authentication**: User authentication and tool-level authorization via Keycloak
- ✅ **Secure Credential Management**: Keycloak credentials stored in Kubernetes Secrets (never in plain text)
- ✅ **Dynamic Secrets**: Optional Vault integration for secret rotation
### Application Security
- ✅ **Input Validation**: Comprehensive validation of user inputs and kubectl parameters
- ✅ **Command Injection Prevention**: Validated executor patterns prevent shell command injection
- ✅ **LLM Output Validation**: Prevents prompt injection attacks via strict output parsing
- ✅ **JSON Marshaling Security**: Proper error handling prevents data leakage
- ✅ **HTTP Timeout Enforcement**: All HTTP clients configured with 30-second timeouts to prevent resource exhaustion
### Supply Chain Security
- ✅ **Pinned Container Images**: All base images use SHA256 digests for reproducibility and security
- ✅ **Minimal Base Images**: UBI9-minimal reduces attack surface
- ✅ **SBOM Generation**: Software Bill of Materials via `make sbom`
### Observability & Hardening
- ✅ **Standardized Health Endpoints**: All services expose `/health` for liveness/readiness probes
- ✅ **Security Warnings**: Development mode configurations (e.g., Keycloak dev mode) clearly flagged
**Security is not a constraint—it's a feature.** This demo proves you can build powerful AI applications with enterprise-grade security on OpenShift.
See [docs/security.md](docs/security.md) for comprehensive security documentation.
## Deployment Targets
This demo is portable across OpenShift environments:
- **SNO on AWS** (primary): Single Node OpenShift with GPU (e.g., g6.4xlarge with NVIDIA L4)
- **ROSA (AWS)**: Red Hat OpenShift on AWS
- **ARO (Azure)**: Azure Red Hat OpenShift
- **Multi-node OCP**: Any OpenShift 4.16+ cluster
Environment-specific settings (ingress domains, storage classes, resource limits) are managed via Kustomize overlays. See [docs/deployment-targets.md](docs/deployment-targets.md) for details.
## Claude Code Skill Usage
This repository includes the `/openshift-mcp-gateway-demo` skill for full automation.
### Loading the Skill
1. **Open this project in Claude Code** (must be the repository root directory)
2. **Restart Claude Code** if the skill doesn't auto-load (it should discover `.claude/skills/` automatically)
3. **Verify**: Type `/` in chat and confirm `/openshift-mcp-gateway-demo` appears in the skills list
### Available Commands
- `/openshift-mcp-gateway-demo setup [environment]` — Auto-detect or specify environment
- `/openshift-mcp-gateway-demo run [script]` — Execute demo script
- `/openshift-mcp-gateway-demo verify` — Run health checks
- `/openshift-mcp-gateway-demo status` — Show current status
- `/openshift-mcp-gateway-demo teardown` — Clean removal
### Troubleshooting
If the skill doesn't appear, see the [Skill Troubleshooting Guide](.claude/skills/openshift-mcp-gateway-demo/README.md).
## Documentation
- [Architecture](docs/architecture.md) — Component descriptions and network flows
- [Security Guide](docs/security.md) — OpenShift security features and best practices
- [Tutorial](docs/tutorial.md) — Step-by-step walkthrough
- [AWS GPU Deployment](docs/AWS-GPU-DEPLOYMENT.md) — OpenShift AI with NVIDIA GPU (g6.4xlarge)
- [Demo Script](docs/demo-script.md) — Presenter guide for live demos
- [Deployment Targets](docs/deployment-targets.md) — Deploying to different OpenShift environments
- [Troubleshooting](docs/troubleshooting.md) — Common issues and solutions
- [Vault Addon](docs/vault-addon.md) — Optional Vault integration
## Project Structure
```
openshift-mcp-gateway-demo/
├── cmd/ # Go source code
│ ├── openshift-mcp-gateway-demo-servers/ # Weather and echo tools
│ └── devops-agent/ # DevOps agent with vLLM
├── deploy/ # Kubernetes/OpenShift manifests
│ ├── base/ # Portable base manifests
│ ├── overlays/ # Environment-specific overlays
│ └── operators/ # Operator subscriptions
├── scripts/ # Automation scripts
├── config/claude-code/ # Claude Code MCP configuration
├── .claude/skills/openshift-mcp-gateway-demo/ # Skill for automation
└── docs/ # Documentation
```
## Development
```bash
# Build Go binaries
make build
# Run tests
make test
# Build container images
make image-build
# Lint code and manifests
make lint
# Validate documentation
make check-docs
# Generate SBOM
make sbom
```
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run `make lint` and `make test`
5. Submit a pull request
See [SECURITY.md](SECURITY.md) for security reporting guidelines.
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Kuadrant](https://kuadrant.io/) for the mcp-gateway
- [Red Hat OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift) for the platform
- [Model Context Protocol](https://modelcontextprotocol.io/) for the open standard
- [Anthropic](https://www.anthropic.com/) for Claude and Claude Code
