Skip to content

Commit c2ff4fe

Browse files
mtodorcoderabbitai[bot]
mtodor
and
coderabbitai[bot]
authored
ROX-33010: Add MCP Gateway integraton to Helm chart (#118)
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 parent ecf4dda commit c2ff4fe

6 files changed

Lines changed: 141 additions & 1 deletion

File tree

‎charts/stackrox-mcp/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,18 @@ The following table lists the configurable parameters of the StackRox MCP chart
142142
| `openshift.route.tls.insecureEdgeTerminationPolicy` | Policy for insecure edge traffic | `Redirect` |
143143
| `openshift.route.tls.destinationCACertificate` | CA certificate for pod verification | `""` |
144144

145+
### MCP Gateway Integration
146+
147+
| Parameter | Description | Default |
148+
|-----------|-------------|---------|
149+
| `mcpGateway.enabled` | Enable MCP Gateway integration | `false` |
150+
| `mcpGateway.gateway.name` | Name of the MCP Gateway resource | `mcp-gateway` |
151+
| `mcpGateway.gateway.namespace` | Namespace of the MCP Gateway resource | `gateway-system` |
152+
| `mcpGateway.hostname` | Internal routing hostname for the HTTPRoute | `<fullname>.mcp.local` |
153+
| `mcpGateway.toolPrefix` | Prefix for tools exposed via the gateway | `stackrox_` |
154+
155+
**Note:** Requires [MCP Gateway](https://github.com/Kuadrant/mcp-gateway) to be installed on the cluster. The chart validates that the required CRDs (`gateway.networking.k8s.io/v1/HTTPRoute` and `mcp.kuadrant.io/v1alpha1/MCPServerRegistration`) are available and fails with a descriptive error if they are not. When MCP Gateway is enabled, `replicaCount` must be set to `1` — the Gateway API's HTTPRoute bypasses Service-level session affinity, so multiple replicas would break stateful MCP sessions. See [MCP Gateway Integration](../../docs/mcp-gateway-integration.md) for details.
156+
145157
### Scheduling
146158

147159
| Parameter | Description | Default |
@@ -351,6 +363,8 @@ helm install stackrox-mcp charts/stackrox-mcp \
351363

352364
### High Availability Setup
353365

366+
**Note:** High availability with multiple replicas is not supported when MCP Gateway is enabled (`mcpGateway.enabled=true`). See [MCP Gateway Integration](#mcp-gateway-integration) for details.
367+
354368
For high availability with multiple replicas:
355369

356370
```yaml

‎charts/stackrox-mcp/templates/_helpers.tpl‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Image reference
4646
*/}}
4747
{{- define "stackrox-mcp.image" -}}
4848
{{- $tag := .Values.image.tag | default .Chart.AppVersion }}
49-
{{- printf "%s/%s:%s" .Values.image.registry .Values.image.repository $tag }}
49+
{{- print .Values.image.registry "/" .Values.image.repository ":" $tag }}
5050
{{- end }}
5151

5252
{{/*

‎charts/stackrox-mcp/templates/http-route.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{{- if .Values.mcpGateway.enabled }}
2+
{{- if gt (int .Values.replicaCount) 1 }}
3+
{{- fail "When MCP Gateway is enabled (mcpGateway.enabled=true), replicaCount must be set to 1. Multiple replicas will cause MCP client connections to land on different pods, breaking stateful MCP sessions. Set replicaCount=1 in your values." }}
4+
{{- end }}
5+
{{- if not (.Capabilities.APIVersions.Has "gateway.networking.k8s.io/v1/HTTPRoute") }}
6+
{{- fail "MCP Gateway integration requires the Gateway API (gateway.networking.k8s.io/v1/HTTPRoute). Install Gateway API CRDs before enabling mcpGateway." }}
7+
{{- end }}
8+
apiVersion: gateway.networking.k8s.io/v1
9+
kind: HTTPRoute
10+
metadata:
11+
name: {{ include "stackrox-mcp.fullname" . }}
12+
namespace: {{ .Release.Namespace }}
13+
labels:
14+
{{- include "stackrox-mcp.labels" . | nindent 4 }}
15+
spec:
16+
parentRefs:
17+
- name: {{ .Values.mcpGateway.gateway.name }}
18+
namespace: {{ .Values.mcpGateway.gateway.namespace }}
19+
hostnames:
20+
- {{ .Values.mcpGateway.hostname | default (printf "%s.mcp.local" (include "stackrox-mcp.fullname" .)) | quote }}
21+
rules:
22+
- matches:
23+
- path:
24+
type: PathPrefix
25+
value: /mcp
26+
backendRefs:
27+
- name: {{ include "stackrox-mcp.fullname" . }}
28+
port: {{ .Values.service.port }}
29+
{{- end }}

‎charts/stackrox-mcp/templates/mcp-server-registration.yaml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{{- if .Values.mcpGateway.enabled }}
2+
{{- if not (.Capabilities.APIVersions.Has "mcp.kuadrant.io/v1alpha1/MCPServerRegistration") }}
3+
{{- fail "MCP Gateway integration requires the MCPServerRegistration CRD (mcp.kuadrant.io/v1alpha1/MCPServerRegistration). Install MCP Gateway (https://github.com/Kuadrant/mcp-gateway) before enabling mcpGateway." }}
4+
{{- end }}
5+
apiVersion: mcp.kuadrant.io/v1alpha1
6+
kind: MCPServerRegistration
7+
metadata:
8+
name: {{ include "stackrox-mcp.fullname" . }}
9+
namespace: {{ .Release.Namespace }}
10+
labels:
11+
{{- include "stackrox-mcp.labels" . | nindent 4 }}
12+
spec:
13+
toolPrefix: {{ .Values.mcpGateway.toolPrefix | quote }}
14+
targetRef:
15+
group: gateway.networking.k8s.io
16+
kind: HTTPRoute
17+
name: {{ include "stackrox-mcp.fullname" . }}
18+
namespace: {{ .Release.Namespace }}
19+
{{- end }}

‎charts/stackrox-mcp/values.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,22 @@ config:
184184
configManager:
185185
enabled: true
186186

187+
# MCP Gateway integration (opt-in)
188+
# Requires MCP Gateway (https://github.com/Kuadrant/mcp-gateway) to be installed on the cluster
189+
mcpGateway:
190+
enabled: false
191+
192+
# Main MCP Gateway reference (this is usually Gateway that gathers all MCP servers)
193+
gateway:
194+
name: mcp-gateway
195+
namespace: gateway-system
196+
197+
# Hostname for the HTTPRoute
198+
hostname: ""
199+
200+
# Tool prefix to avoid naming conflicts when aggregating tools through the gateway
201+
toolPrefix: stackrox_
202+
187203
# Additional environment variables (advanced use)
188204
# These will be added directly to the container
189205
extraEnv: []

‎docs/mcp-gateway-integration.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# MCP Gateway Integration
2+
3+
This guide describes how to integrate the StackRox MCP server with [MCP Gateway](https://github.com/Kuadrant/mcp-gateway), enabling tool aggregation behind a centralized gateway endpoint.
4+
5+
## Overview
6+
7+
MCP Gateway is an Envoy-based system that aggregates multiple MCP servers behind a single endpoint. It uses Gateway API resources and a custom `MCPServerRegistration` CRD to discover and route requests to backend MCP servers.
8+
9+
When enabled, the Helm chart creates:
10+
- **HTTPRoute** — routes `/mcp` traffic from the gateway to the StackRox MCP service
11+
- **MCPServerRegistration** — registers the server with the gateway using a tool prefix to avoid naming conflicts
12+
13+
## Prerequisites
14+
15+
- [MCP Gateway](https://github.com/Kuadrant/mcp-gateway) installed on the cluster ([OpenShift installation guide](https://github.com/Kuadrant/mcp-gateway/tree/main/config/openshift))
16+
17+
The Helm chart validates that the required CRDs are available and fails with a descriptive error if they are not.
18+
19+
## Installation
20+
21+
**Important:** When MCP Gateway is enabled, `replicaCount` must be set to `1`. The Gateway API's HTTPRoute bypasses Kubernetes Service-level session affinity, so multiple replicas would cause MCP client connections to land on different pods, breaking stateful MCP sessions.
22+
23+
```bash
24+
helm install stackrox-mcp charts/stackrox-mcp \
25+
--namespace stackrox-mcp \
26+
--create-namespace \
27+
--set replicaCount=1 \
28+
--set mcpGateway.enabled=true \
29+
--set mcpGateway.hostname=stackrox-mcp.mcp.local \
30+
--set config.central.url=<your-central-url>
31+
```
32+
33+
## Configuration Reference
34+
35+
| Parameter | Description | Default |
36+
|-----------|-------------|---------|
37+
| `mcpGateway.enabled` | Enable MCP Gateway integration | `false` |
38+
| `mcpGateway.gateway.name` | Name of the MCP Gateway resource | `mcp-gateway` |
39+
| `mcpGateway.gateway.namespace` | Namespace of the MCP Gateway resource | `gateway-system` |
40+
| `mcpGateway.hostname` | Internal routing hostname for the HTTPRoute | `<fullname>.mcp.local` |
41+
| `mcpGateway.toolPrefix` | Prefix for tools exposed via the gateway | `stackrox_` |
42+
43+
## Verification
44+
45+
```bash
46+
curl -X POST https://$(oc get routes -n gateway-system -o jsonpath='{ .items[0].spec.host }')/mcp \
47+
-H "Content-Type: application/json" \
48+
-d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
49+
```
50+
51+
## Architecture
52+
53+
```
54+
MCP Client
55+
→ MCP Gateway (gateway-system namespace)
56+
→ HTTPRoute (/mcp)
57+
→ StackRox MCP Service (stackrox-mcp namespace)
58+
→ StackRox MCP Pod(s)
59+
→ StackRox Central API
60+
```
61+
62+
The gateway aggregates tools from all registered MCP servers. StackRox MCP tools are exposed with the configured prefix (e.g., `stackrox_get_deployments_for_cve`).

0 commit comments

Comments
 (0)