Cherry-picks for v0.6.0-rc2

.github/workflows/ci-docs-skip.yaml

@@ -0,0 +1,55 @@
+name: CI Docs Skip
+
+# Provides pass statuses for required checks when only non-code files change.
+# Without this, PRs touching only these paths can never merge because the real
+# workflows use paths-ignore and never report a status for the required checks.
+# The paths list below is the union of all paths-ignore entries from
+# images.yaml, tests.yaml, and code-style.yaml.
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    branches: ['main']
+    paths:
+      - '**.md'
+      - 'docs/**'
+      - 'examples/**'
+      - 'LICENSE'
+      - 'charts/**'
+      - 'evals/**'
+      - 'tests/servers/**'
+      - '.coderabbit.yaml'
+      - '.gitignore'
+  merge_group:
+    types: [checks_requested]
+
+jobs:
+  build:
+    name: Build ${{ matrix.image }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - image: mcp-gateway
+          - image: mcp-controller
+    steps:
+      - run: echo "Docs-only change, skipping build"
+
+  unit-tests:
+    name: Unit Tests
+    strategy:
+      matrix:
+        go-version: [1.22.x]
+        platform: [ubuntu-latest]
+    runs-on: ${{ matrix.platform }}
+    steps:
+      - run: echo "Docs-only change, skipping tests"
+
+  code-style:
+    name: Code Style Checks
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Docs-only change, skipping code style"

.github/workflows/gevals.yaml

@@ -39,8 +39,8 @@ jobs:
     name: Run MCP Evaluation
     runs-on: ubuntu-latest
     env:
-      MODEL_KEY: ${{ secrets.MODEL_KEY }}
-      MODEL_BASE_URL: ${{ secrets.MODEL_BASE_URL }}
+      OPENAI_API_KEY: ${{ secrets.MODEL_KEY }}
+      OPENAI_BASE_URL: ${{ secrets.MODEL_BASE_URL }}
 
     steps:
       - name: Checkout
@@ -77,53 +77,63 @@ jobs:
           echo "Gateway is ready!"
 
       - name: Setup Fallback LLM (Ollama)
-        if: env.MODEL_KEY == ''
+        if: env.OPENAI_API_KEY == ''
         uses: ai-action/setup-ollama@v2
 
       - name: Cache Ollama Models
-        if: env.MODEL_KEY == ''
+        if: env.OPENAI_API_KEY == ''
         uses: actions/cache@v4
         with:
           path: ~/.ollama
           key: ${{ runner.os }}-ollama-qwen2.5-1.5b
 
       - name: Run Agent (Fallback)
-        if: env.MODEL_KEY == ''
+        if: env.OPENAI_API_KEY == ''
         run: |
           echo "No MODEL_KEY secret found. Starting Ollama..."
-          
+
           # Start Ollama in background
           ollama serve &
-          
+
           # Wait for Ollama to be ready
           echo "Waiting for Ollama to be ready..."
           timeout 60s bash -c 'until curl -s http://localhost:11434 > /dev/null; do sleep 2; done'
-          
+
           MODEL_NAME="qwen2.5:1.5b"
-          
+
           # Pull the model (Ollama will skip if cached/present)
           echo "Pulling model $MODEL_NAME..."
           ollama pull $MODEL_NAME
-          
+
           # Configure environment for mcpchecker
-          echo "MODEL_BASE_URL=http://localhost:11434/v1" >> $GITHUB_ENV
-          echo "MODEL_KEY=ollama" >> $GITHUB_ENV
-          
+          echo "OPENAI_BASE_URL=http://localhost:11434/v1" >> $GITHUB_ENV
+          echo "OPENAI_API_KEY=ollama" >> $GITHUB_ENV
+
           # Update agent.yaml to use the fallback model
-          sed -i "s/model: .*/model: \"$MODEL_NAME\"/" evals/gemini-agent/agent.yaml
-          
+          sed -i "s/model: .*/model: \"openai:$MODEL_NAME\"/" evals/gemini-agent/agent.yaml
+
           echo "Ollama setup complete using model $MODEL_NAME"
 
-      - name: Run mcpchecker (Manual)
+      - name: Run mcpchecker
         run: |
           echo "Installing mcpchecker..."
           go install github.com/mcpchecker/mcpchecker/cmd/mcpchecker@latest
-          
+
           echo "Running mcpchecker..."
-          # Ensure GOBIN is in PATH if not already (github actions usually has it)
           export PATH=$PATH:$(go env GOPATH)/bin
           mcpchecker check --verbose evals/gemini-agent/eval.yaml
 
+      - name: Verify Results
+        if: always()
+        run: |
+          export PATH=$PATH:$(go env GOPATH)/bin
+          RESULTS_FILE=$(ls mcpchecker-*-out.json 2>/dev/null | head -1)
+          if [ -z "$RESULTS_FILE" ]; then
+            echo "No results file found — mcpchecker may have crashed"
+            exit 1
+          fi
+          mcpchecker verify --task 1.0 --assertion 1.0 "$RESULTS_FILE"
+
       - name: Upload Evaluation Results
         if: always()
         uses: actions/upload-artifact@v4

AGENTS.md

@@ -7,7 +7,7 @@ This file provides guidance to AI Agents when working with this repository.
 MCP Gateway is an Envoy-based gateway for Model Context Protocol (MCP) servers. Single binary (`mcp-broker-router`) with three components:
 - **MCP Router**: Envoy external processor that routes MCP requests (gRPC on :50051)
 - **MCP Broker**: HTTP service that aggregates tools from multiple MCP servers (HTTP on :8080/mcp)
-- **MCP Controller**: Kubernetes controller that discovers MCP servers via MCPServerRegistration CRDs (optional, `--controller` flag)
+- **MCP Gateway Controller**: Kubernetes controller that discovers MCP servers via MCPServerRegistration CRDs (optional, `--controller` flag)
 
 ## Architecture
 
@@ -255,7 +255,7 @@ This allows AuthPolicy to validate the OAuth token while backends receive their
 ## Test Servers
 
 Six test servers in `config/test-servers/`:
-- **Server1**: Go SDK (tools: hi, time, slow, headers)
+- **Server1**: Go SDK (tools: greet, time, slow, headers)
 - **Server2**: Go SDK (tools: hello_world, time, headers, auth1234, slow)
 - **Server3**: Python FastMCP (tools: time, add, dozen, pi, get_weather, slow)
 - **API Key Server**: Validates Bearer token authentication (tool: hello_world)

CLAUDE.md

@@ -7,7 +7,7 @@ This file provides guidance to Claude Code when working with this repository.
 MCP Gateway is an Envoy-based gateway for Model Context Protocol (MCP) servers. Single binary (`mcp-broker-router`) with three components:
 - **MCP Router**: Envoy external processor that routes MCP requests (gRPC on :50051)
 - **MCP Broker**: HTTP service that aggregates tools from multiple MCP servers (HTTP on :8080/mcp)
-- **MCP Controller**: Kubernetes controller that discovers MCP servers via MCPServerRegistration CRDs (optional, `--controller` flag)
+- **MCP Gateway Controller**: Kubernetes controller that discovers MCP servers via MCPServerRegistration CRDs (optional, `--controller` flag)
 
 # Exploration
 
@@ -273,7 +273,7 @@ This allows AuthPolicy to validate the OAuth token while backends receive their
 ## Test Servers
 
 Test servers in `config/test-servers/`:
-- **Server1**: Go SDK (tools: hi, time, slow, headers)
+- **Server1**: Go SDK (tools: greet, time, slow, headers)
 - **Server2**: Go SDK (tools: hello_world, time, headers, auth1234, slow)
 - **Server3**: Python FastMCP (tools: time, add, dozen, pi, get_weather, slow)
 - **API Key Server**: Validates Bearer token authentication (tool: hello_world)

Makefile

@@ -233,13 +233,13 @@ deploy-redis: ## deploy redis to mcp-system namespace
 
 .PHONY: configure-redis
 configure-redis: deploy-redis ## deploy redis and patch deployment with redis connection
-	kubectl patch deployment $(BROKER_ROUTER_NAME) -n mcp-system --patch-file config/mcp-gateway/overlays/mcp-system/deployment-controller-redis-patch.yaml
+	kubectl patch deployment $(BROKER_ROUTER_NAME) -n $(MCP_GATEWAY_NAMESPACE) --patch-file config/mcp-gateway/overlays/mcp-system/deployment-controller-redis-patch.yaml
 
 # Deploy only the controller
 deploy-controller: install-crd ## Deploy only the controller
 	kubectl apply -k config/mcp-gateway/overlays/mcp-system/
 	@echo "Waiting for controller to be ready..."
-	@kubectl wait --for=condition=Available deployment/mcp-controller -n mcp-system --timeout=$(WAIT_TIME)
+	@kubectl wait --for=condition=Available deployment/mcp-gateway-controller -n mcp-system --timeout=$(WAIT_TIME)
 	@echo "Waiting for MCPGatewayExtension to be ready..."
 	@kubectl wait --for=condition=Ready mcpgatewayextension/mcp-gateway-extension -n mcp-system --timeout=$(WAIT_TIME)
 	@echo "Controller and broker-router are ready"
@@ -256,8 +256,8 @@ endef
 
 .PHONY: restart-all
 restart-all:
-	kubectl rollout restart deployment/$(BROKER_ROUTER_NAME) -n mcp-system 2>/dev/null || true
-	kubectl rollout restart deployment/mcp-controller -n mcp-system 2>/dev/null || true
+	kubectl rollout restart deployment/$(BROKER_ROUTER_NAME) -n $(MCP_GATEWAY_NAMESPACE) 2>/dev/null || true
+	kubectl rollout restart deployment/mcp-gateway-controller -n $(MCP_GATEWAY_NAMESPACE) 2>/dev/null || true
 
 .PHONY: build-and-load-image
 build-and-load-image: kind build-image load-image restart-all  ## Build & load router/broker/controller image into the Kind cluster and restart
@@ -287,7 +287,7 @@ deploy-example: install-crd ## Deploy example MCPServerRegistration resource
 	kubectl apply -f config/samples/mcpserverregistration-test-servers-base.yaml
 	kubectl apply -f config/samples/mcpserverregistration-test-servers-extended.yaml
 	@echo "Waiting for broker-router to be ready..."
-	@kubectl wait --for=condition=Available deployment/$(BROKER_ROUTER_NAME) -n mcp-system --timeout=$(WAIT_TIME)
+	@kubectl wait --for=condition=Available deployment/$(BROKER_ROUTER_NAME) -n $(MCP_GATEWAY_NAMESPACE) --timeout=$(WAIT_TIME)
 
 # Deploy example MCPServerRegistration for everything server only
 deploy-example-minimal: install-crd ## Deploy MCPServerRegistration for everything server
@@ -410,8 +410,8 @@ endef
 reload-controller: build kind ## Build, load to Kind, and restart controller
 	$(CONTAINER_ENGINE) build $(CONTAINER_ENGINE_EXTRA_FLAGS) --file Dockerfile.controller -t $(IMAGE_TAG_BASE):$(IMAGE_TAG) .
 	$(call load-image,$(IMAGE_TAG_BASE):$(IMAGE_TAG))
-	@kubectl rollout restart -n mcp-system deployment/mcp-controller
-	@kubectl rollout status -n mcp-system deployment/mcp-controller --timeout=60s
+	@kubectl rollout restart -n $(MCP_GATEWAY_NAMESPACE) deployment/mcp-gateway-controller
+	@kubectl rollout status -n $(MCP_GATEWAY_NAMESPACE) deployment/mcp-gateway-controller --timeout=60s
 
 .PHONY: reload-broker
 reload-broker: build docker-build kind ## Build, load to Kind, and restart broker
@@ -422,8 +422,8 @@ reload-broker: build docker-build kind ## Build, load to Kind, and restart broke
 .PHONY: reload
 reload: build docker-build kind ## Build, load to Kind, and restart both controller and broker
 	$(call reload-image)
-	@kubectl rollout restart -n $(MCP_GATEWAY_NAMESPACE) deployment/mcp-controller deployment/$(BROKER_ROUTER_NAME)
-	@kubectl rollout status -n $(MCP_GATEWAY_NAMESPACE)deployment/mcp-controller --timeout=60s
+	@kubectl rollout restart -n $(MCP_GATEWAY_NAMESPACE) deployment/mcp-gateway-controller deployment/$(BROKER_ROUTER_NAME)
+	@kubectl rollout status -n $(MCP_GATEWAY_NAMESPACE) deployment/mcp-gateway-controller --timeout=60s
 	@kubectl rollout status -n $(MCP_GATEWAY_NAMESPACE) deployment/$(BROKER_ROUTER_NAME) --timeout=60s
 
 ##@ E2E Testing
@@ -726,9 +726,9 @@ ifeq ($(ISTIO_TRACING),1)
 		-p='{"spec":{"values":{"meshConfig":{"enableTracing":true,"defaultConfig":{"tracing":{}},"extensionProviders":[{"name":"tempo-otlp","opentelemetry":{"port":4317,"service":"$(OTEL_COLLECTOR_HOST)"}}]}}}}'
 	@sleep 5
 endif
-	kubectl set env deployment/mcp-gateway -n mcp-system \
+	kubectl set env deployment/mcp-gateway -n $(MCP_GATEWAY_NAMESPACE) \
 		OTEL_EXPORTER_OTLP_ENDPOINT="$(OTEL_COLLECTOR_HTTP)" OTEL_EXPORTER_OTLP_INSECURE="true"
-	@kubectl rollout status deployment/mcp-gateway -n mcp-system --timeout=120s
+	@kubectl rollout status deployment/mcp-gateway -n $(MCP_GATEWAY_NAMESPACE) --timeout=120s
 ifeq ($(AUTH_TRACING),1)
 	@if ! kubectl get authorino -n kuadrant-system 2>/dev/null | grep -q authorino; then \
 		$(MAKE) auth-example-setup; \

README.md

@@ -91,6 +91,7 @@ This will:
 - Configure the mcp-broker with OAuth environment variables
 - Apply AuthPolicy for token validation/exchange on the /mcp endpoint, including tool authorization via keycloak group mappings (both via Keycloak)
 - Apply additional OAuth configurations
+- Deploy several test MCP servers including OIDC-enabled MCP server
 
 The mcp-broker now serves OAuth discovery information at `/.well-known/oauth-protected-resource`.
 

api/v1alpha1/mcpgatewayextension_types.go

@@ -207,8 +207,9 @@ type MCPGatewayExtensionTargetReference struct {
 
 	// sectionName is the name of a listener on the target Gateway. The controller will
 	// read the listener's port and hostname to configure the MCP Gateway instance.
-	// This allows multiple MCPGatewayExtensions to target different listeners on the
-	// same Gateway, each with their own MCP Gateway instance.
+	// Only one MCPGatewayExtension is allowed per namespace. MCPGatewayExtensions in
+	// different namespaces may target different listeners on the same Gateway, provided
+	// those listeners use different ports.
 	// +required
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=253

build/auth.mk

@@ -14,7 +14,7 @@ auth-example-setup: cert-manager-install kuadrant-install keycloak-install ## Se
 	@echo ""
 	@echo "Prerequisites: make local-env-setup should be completed"
 	@echo ""
-	@echo "Step 1/5: Configuring OAuth environment variables..."
+	@echo "Step 1/6: Configuring OAuth environment variables..."
 	@kubectl set env deployment/mcp-gateway \
 		OAUTH_RESOURCE_NAME="MCP Server" \
 		OAUTH_RESOURCE="http://mcp.127-0-0-1.sslip.io:8001/mcp" \
@@ -24,24 +24,29 @@ auth-example-setup: cert-manager-install kuadrant-install keycloak-install ## Se
 		-n mcp-system
 	@echo "✅ OAuth environment variables configured"
 	@echo ""
-	@echo "Step 2/5: Installing Vault..."
+	@echo "Step 2/6: Installing Vault..."
 	@bin/kustomize build config/vault | bin/yq 'select(.kind == "Deployment").spec.template.spec.containers[0].args += ["-dev-root-token-id=root"] | .' | kubectl apply -f -
 	@echo "✅ Vault installed"
 	@echo ""
-	@echo "Step 3/5: Applying AuthPolicy configurations..."
+	@echo "Step 3/6: Applying AuthPolicy configurations..."
 	@kubectl apply -k ./config/samples/oauth-token-exchange/
 	@kubectl patch mcpgatewayextension mcp-gateway-extension -n mcp-system --type='merge' \
 		-p='{"spec":{"trustedHeadersKey":{"secretName":"trusted-headers-public-key"}}}'
 	@echo "✅ AuthPolicy configurations applied"
 	@echo ""
-	@echo "Step 4/5: Configuring CORS rules for the OpenID Connect Client Registration endpoint..."
+	@echo "Step 4/6: Configuring CORS rules for the OpenID Connect Client Registration endpoint..."
 	@kubectl apply -f ./config/keycloak/preflight_envoyfilter.yaml
 	@echo "✅ CORS configured"
 	@echo ""
-	@echo "Step 5/5: Patch Authorino deployment to be able to connect to Keycloak..."
+	@echo "Step 5/6: Patch Authorino deployment to be able to connect to Keycloak..."
 	@./utils/patch-authorino-to-keycloak.sh
 	@echo "✅ Authorino deployment patched"
 	@echo ""
+	@echo "Step 6/6: Deploying test MCP servers..."
+	@"$(MAKE)" deploy-test-servers
+	@"$(MAKE)" deploy-example
+	@echo "✅ Test MCP servers deployed and configured"
+	@echo ""
 	@echo "🎉 OAuth example setup complete!"
 	@echo ""
 	@echo "The mcp-broker now serves OAuth discovery information at:"

build/ci.mk

@@ -63,7 +63,7 @@ ci-auth-setup: cert-manager-install kuadrant-install ## Setup auth infrastructur
 .PHONY: ci-debug-logs
 ci-debug-logs: ## Collect logs for debugging CI failures
 	@echo "=== Controller logs ==="
-	-$(KUBECTL) logs -n mcp-system deployment/mcp-controller --tail=100
+	-$(KUBECTL) logs -n mcp-system deployment/mcp-gateway-controller --tail=100
 	@echo "=== MCPGatewayExtensions ==="
 	-$(KUBECTL) get mcpgatewayextensions -A
 	@echo "=== MCPServerRegistrations ==="

build/e2e.mk

@@ -24,7 +24,7 @@ test-e2e: ci-setup test-e2e-run ## Run full e2e test suite (setup + run)
 .PHONY: test-e2e-happy
 test-e2e-happy: test-e2e-deps ## Quick e2e test run for local development (no setup)
 	@echo "Running e2e tests (local mode)..."
-	$(GINKGO) -v --tags=e2e --timeout=$(E2E_TIMEOUT) --focus="[Happy]" ./tests/e2e
+	$(GINKGO) -v --tags=e2e --timeout=$(E2E_TIMEOUT) --focus="\[Happy\]" ./tests/e2e
 
 .PHONY: test-e2e-cleanup
 test-e2e-cleanup: ## Clean up e2e test resources
@@ -48,8 +48,8 @@ test-e2e-auth-ci: test-e2e-deps enable-debug-logging ## Run auth e2e tests only
 
 .PHONY: enable-debug-logging
 enable-debug-logging: ## Enable debug logging on controller and wait for restart
-	@echo "Enabling debug logging on mcp-controller..."
-	kubectl patch deployment mcp-controller -n mcp-system --type='json' \
+	@echo "Enabling debug logging on mcp-gateway-controller..."
+	kubectl patch deployment mcp-gateway-controller -n mcp-system --type='json' \
 		-p='[{"op": "replace", "path": "/spec/template/spec/containers/0/command", "value": ["./mcp_controller", "--log-level=-4"]}]'
 	@echo "Waiting for controller rollout..."
-	kubectl rollout status deployment/mcp-controller -n mcp-system --timeout=120s
+	kubectl rollout status deployment/mcp-gateway-controller -n mcp-system --timeout=120s

build/setup.mk

@@ -10,7 +10,7 @@ setup-cluster-base: tools kind-create-cluster build-and-load-image gateway-api-i
 deploy-controller-only: ## Deploy only the controller (tests create their own MCPGatewayExtensions)
 	$(KUBECTL) apply -k config/mcp-gateway/overlays/ci/
 	@echo "Waiting for controller to be ready..."
-	@$(KUBECTL) wait --for=condition=available --timeout=180s deployment/mcp-controller -n mcp-system
+	@$(KUBECTL) wait --for=condition=available --timeout=180s deployment/mcp-gateway-controller -n mcp-system
 
 # Wait for test server deployments
 .PHONY: wait-test-servers

bundle/manifests/mcp-gateway.clusterserviceversion.yaml

@@ -161,7 +161,7 @@ spec:
         - label:
             app: mcp-controller
             component: controller
-          name: mcp-controller
+          name: mcp-gateway-controller
           spec:
             replicas: 1
             selector:

bundle/manifests/mcp.kuadrant.io_mcpgatewayextensions.yaml

@@ -130,8 +130,9 @@ spec:
                     description: |-
                       sectionName is the name of a listener on the target Gateway. The controller will
                       read the listener's port and hostname to configure the MCP Gateway instance.
-                      This allows multiple MCPGatewayExtensions to target different listeners on the
-                      same Gateway, each with their own MCP Gateway instance.
+                      Only one MCPGatewayExtension is allowed per namespace. MCPGatewayExtensions in
+                      different namespaces may target different listeners on the same Gateway, provided
+                      those listeners use different ports.
                     maxLength: 253
                     minLength: 1
                     type: string

charts/README.md

@@ -7,7 +7,7 @@ This directory contains the Helm chart for deploying MCP Gateway to Kubernetes.
 ## Overview
 
 The MCP Gateway Helm chart deploys:
-- **MCP Controller**: Manages MCPGatewayExtension, MCPServerRegistration, and MCPVirtualServer custom resources
+- **MCP Gateway Controller**: Manages MCPGatewayExtension, MCPServerRegistration, and MCPVirtualServer custom resources
 - **MCPGatewayExtension**: Custom resource that triggers the controller to deploy the broker-router
 - **Custom Resource Definitions (CRDs)**: MCPGatewayExtension, MCPServerRegistration, and MCPVirtualServer
 - **RBAC**: Service accounts, roles, and bindings for secure operation

charts/mcp-gateway/crds/mcp.kuadrant.io_mcpgatewayextensions.yaml

@@ -130,8 +130,9 @@ spec:
                     description: |-
                       sectionName is the name of a listener on the target Gateway. The controller will
                       read the listener's port and hostname to configure the MCP Gateway instance.
-                      This allows multiple MCPGatewayExtensions to target different listeners on the
-                      same Gateway, each with their own MCP Gateway instance.
+                      Only one MCPGatewayExtension is allowed per namespace. MCPGatewayExtensions in
+                      different namespaces may target different listeners on the same Gateway, provided
+                      those listeners use different ports.
                     maxLength: 253
                     minLength: 1
                     type: string