Operator: Change default proxy mode from SSE to streamable-http (#2521)

danbarr · web-flow · commit b797d8921b26 · 2025-11-08T17:58:38.000Z
* Change default proxy mode from SSE to streamable-http Update the Kubernetes Operator to default to streamable-http proxy mode instead of the deprecated SSE transport for stdio-based MCP servers. Changes: - Update CRD default annotation from sse to streamable-http - Update controller default logic to use streamable-http - Update unit tests to expect streamable-http as default - Regenerate CRD manifests and documentation - Bump operator-crds chart version from 0.0.52 to 0.0.53 - Bump operator chart version from 0.3.7 to 0.3.8 - Add explicit proxyMode: sse to existing stdio e2e tests - Add new stdio-streamable-http e2e test scenarios for both single-tenancy and multi-tenancy The streamable-http transport is the recommended approach per the MCP specification. Users can still explicitly set proxyMode: sse if needed. Fixes #2211 Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> * Bump operator chart to 0.4.0 Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --------- Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> Co-authored-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
diff --git a/cmd/thv-operator/api/v1alpha1/mcpserver_types.go b/cmd/thv-operator/api/v1alpha1/mcpserver_types.go
@@ -61,7 +61,7 @@ type MCPServerSpec struct {
 	// ProxyMode is the proxy mode for stdio transport (sse or streamable-http)
 	// This setting is only used when Transport is "stdio"
 	// +kubebuilder:validation:Enum=sse;streamable-http
-	// +kubebuilder:default=sse
+	// +kubebuilder:default=streamable-http
 	// +optional
 	ProxyMode string `json:"proxyMode,omitempty"`
 
diff --git a/cmd/thv-operator/controllers/mcpserver_runconfig.go b/cmd/thv-operator/controllers/mcpserver_runconfig.go
@@ -123,7 +123,7 @@ func (r *MCPServerReconciler) createRunConfigFromMCPServer(m *mcpv1alpha1.MCPSer
 
 	proxyMode := m.Spec.ProxyMode
 	if proxyMode == "" {
-		proxyMode = "sse" // Default to SSE for backward compatibility
+		proxyMode = "streamable-http" // Default to streamable-http (SSE is deprecated)
 	}
 
 	options := []runner.RunConfigBuilderOption{
diff --git a/cmd/thv-operator/controllers/mcpserver_runconfig_test.go b/cmd/thv-operator/controllers/mcpserver_runconfig_test.go
@@ -186,7 +186,7 @@ func TestCreateRunConfigFromMCPServer(t *testing.T) {
 			},
 		},
 		{
-			name: "proxy mode defaults to sse when not specified",
+			name: "proxy mode defaults to streamable-http when not specified",
 			mcpServer: &mcpv1alpha1.MCPServer{
 				ObjectMeta: metav1.ObjectMeta{
 					Name:      "default-proxy-mode-server",
@@ -205,7 +205,7 @@ func TestCreateRunConfigFromMCPServer(t *testing.T) {
 				assert.Equal(t, testImage, config.Image)
 				assert.Equal(t, transporttypes.TransportTypeStdio, config.Transport)
 				assert.Equal(t, 8080, config.Port)
-				assert.Equal(t, transporttypes.ProxyModeSSE, config.ProxyMode, "Should default to sse")
+				assert.Equal(t, transporttypes.ProxyModeStreamableHTTP, config.ProxyMode, "Should default to streamable-http")
 			},
 		},
 		{
diff --git a/deploy/charts/operator-crds/Chart.yaml b/deploy/charts/operator-crds/Chart.yaml
@@ -2,5 +2,5 @@ apiVersion: v2
 name: toolhive-operator-crds
 description: A Helm chart for installing the ToolHive Operator CRDs into Kubernetes.
 type: application
-version: 0.0.52
+version: 0.0.53
 appVersion: "0.0.1"
diff --git a/deploy/charts/operator-crds/README.md b/deploy/charts/operator-crds/README.md
@@ -1,7 +1,7 @@
 
 # ToolHive Operator CRDs Helm Chart
 
-![Version: 0.0.52](https://img.shields.io/badge/Version-0.0.52-informational?style=flat-square)
+![Version: 0.0.53](https://img.shields.io/badge/Version-0.0.53-informational?style=flat-square)
 ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square)
 
 A Helm chart for installing the ToolHive Operator CRDs into Kubernetes.
diff --git a/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpservers.yaml b/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpservers.yaml
@@ -344,7 +344,7 @@ spec:
                 minimum: 1
                 type: integer
               proxyMode:
-                default: sse
+                default: streamable-http
                 description: |-
                   ProxyMode is the proxy mode for stdio transport (sse or streamable-http)
                   This setting is only used when Transport is "stdio"
diff --git a/deploy/charts/operator/Chart.yaml b/deploy/charts/operator/Chart.yaml
@@ -2,5 +2,5 @@ apiVersion: v2
 name: toolhive-operator
 description: A Helm chart for deploying the ToolHive Operator into Kubernetes.
 type: application
-version: 0.3.7
+version: 0.4.0
 appVersion: "0.5.2"
diff --git a/deploy/charts/operator/README.md b/deploy/charts/operator/README.md
@@ -1,7 +1,7 @@
 
 # ToolHive Operator Helm Chart
 
-![Version: 0.3.7](https://img.shields.io/badge/Version-0.3.7-informational?style=flat-square)
+![Version: 0.4.0](https://img.shields.io/badge/Version-0.4.0-informational?style=flat-square)
 ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square)
 
 A Helm chart for deploying the ToolHive Operator into Kubernetes.
diff --git a/docs/operator/crd-api.md b/docs/operator/crd-api.md
diff --git a/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-pod-running.yaml b/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-pod-running.yaml
@@ -0,0 +1,7 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: yardstick
+  namespace: test-namespace
+status:
+  availableReplicas: 1
diff --git a/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-proxy-runner-running.yaml b/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-proxy-runner-running.yaml
@@ -0,0 +1,17 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: yardstick
+  namespace: test-namespace
+spec:
+  replicas: 1
+status:
+  # Ensure deployment is available and progressing successfully
+  (conditions[?type == 'Available'] | [0].status): "True"
+  (conditions[?type == 'Progressing'] | [0].status): "True"
+  (conditions[?type == 'Progressing'] | [0].reason): "NewReplicaSetAvailable"
+  # Ensure all replicas are ready and available
+  replicas: 1
+  readyReplicas: 1
+  availableReplicas: 1
+  updatedReplicas: 1
diff --git a/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-proxy-runner-svc.yaml b/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-proxy-runner-svc.yaml
@@ -0,0 +1,5 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: mcp-yardstick-proxy
+  namespace: test-namespace
diff --git a/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-running.yaml b/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-running.yaml
@@ -0,0 +1,8 @@
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPServer
+metadata:
+  name: yardstick
+  namespace: test-namespace
+status:
+  message: "MCP server is running"
+  phase: "Running"
diff --git a/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/chainsaw-test.yaml b/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/chainsaw-test.yaml
@@ -0,0 +1,129 @@
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: stdio-streamable-http-mcp-server
+spec:
+  description: Deploys STDIO MCP server with streamable-http proxy mode and verifies it's running
+  timeouts:
+    apply: 30s
+    assert: 60s
+    cleanup: 30s
+    exec: 300s
+  steps:
+  - name: verify-operator
+    description: Ensure operator is ready before testing
+    try:
+    - assert:
+        file: ../../setup/assert-operator-ready.yaml
+    - assert:
+        file: ../../setup/namespace.yaml
+      
+  - name: deploy-mcpserver
+    description: Deploy a basic MCPServer instance and verify it's ready
+    try:
+    - apply:
+        file: mcpserver.yaml
+    - assert:
+        file: mcpserver.yaml
+    - assert:
+        file: assert-mcpserver-running.yaml
+    - assert:
+        file: assert-mcpserver-pod-running.yaml
+    - assert:
+        file: assert-mcpserver-proxy-runner-running.yaml
+    - assert:
+        file: assert-mcpserver-proxy-runner-svc.yaml
+    - assert:
+        file: ../common/proxyrunner-role.yaml
+    - assert:
+        file: ../common/proxyrunner-rolebinding.yaml
+    - assert:
+        file: ../common/proxyrunner-serviceaccount.yaml
+    - apply:
+        file: ../common/proxy-svc-loadbalancer.yaml
+    - assert:
+        file: ../common/assert-proxy-svc-loadbalancer-ip.yaml
+
+  - name: test-mcp-server
+    description: Test the streamable-http->STDIO MCP server by sending requests at the toolhive proxy
+    try:
+    - script:
+        content: |
+          # Get LoadBalancer external IP
+          echo "Getting LoadBalancer external IP for service mcp-yardstick-proxy-lb..."
+          EXTERNAL_IP=$(kubectl get svc mcp-yardstick-proxy-lb -n test-namespace -o jsonpath='{.status.loadBalancer.ingress[0].ip}' 2>/dev/null || echo "")
+          
+          if [ -z "$EXTERNAL_IP" ]; then
+            echo "LoadBalancer did not get external IP within timeout"
+            kubectl describe svc mcp-yardstick-proxy-lb -n test-namespace
+            exit 1
+          fi
+          
+          # Wait additional time for LoadBalancer to be ready
+          echo "Waiting for LoadBalancer to be ready..."
+          
+          # Function to retry yardstick-client commands with backoff
+          retry_yardstick() {
+            local max_attempts=5
+            local delay=2
+            local attempt=1
+            local cmd="$@"
+            
+            while [ $attempt -le $max_attempts ]; do
+              echo "Attempt $attempt/$max_attempts: $cmd"
+              if eval $cmd; then
+                echo "✓ Command succeeded on attempt $attempt"
+                return 0
+              else
+                echo "! Command failed on attempt $attempt"
+                if [ $attempt -lt $max_attempts ]; then
+                  echo "Waiting ${delay}s before retry..."
+                  sleep $delay
+                  delay=$((delay * 2))  # exponential backoff
+                fi
+              fi
+              attempt=$((attempt + 1))
+            done
+            
+            echo "! Command failed after $max_attempts attempts"
+            return 1
+          }
+          
+          echo "🌊 ========== STREAMABLE-HTTP->STDIO TRANSPORT TESTING =========="
+          echo "📡 Testing streamable-http transport on port 8080..."
+
+          # Test streamable-http endpoint with client binary
+          echo "🌊 Testing streamable-http endpoint with client binary..."
+          if retry_yardstick "yardstick-client -transport streamable-http -address $EXTERNAL_IP -port 8080 -action info"; then
+              echo "✓ streamable-http client connection successful"
+          else
+              echo "! streamable-http client connection failed"
+              exit 1
+          fi
+
+          # Longer delay between calls for CI stability
+
+          # Test listing tools via streamable-http
+          echo "📋 Testing tool listing via streamable-http..."
+          if retry_yardstick "yardstick-client -transport streamable-http -address $EXTERNAL_IP -port 8080 -action list-tools"; then
+              echo "✓ streamable-http tools listing successful"
+          else
+              echo "! streamable-http tools listing failed"
+              exit 1
+          fi
+
+          # Longer delay between calls for CI stability
+
+          echo "🔧 Testing tool calling via streamable-http..."
+          # We want to generate a random string to test the tool calling
+          # and then check if the output contains the string
+          TEST_INPUT_OUTPUT=$(openssl rand -hex 16)
+          if retry_yardstick "timeout 30 yardstick-client -transport streamable-http -address $EXTERNAL_IP -port 8080 -action=call-tool -tool=echo -args='{\"input\":\"$TEST_INPUT_OUTPUT\"}' | grep -q '$TEST_INPUT_OUTPUT'"; then
+              echo "✓ streamable-http tool call returned expected output: $TEST_INPUT_OUTPUT"
+          else
+              echo "! streamable-http tool call failed or timed out"
+              exit 1
+          fi
+
+          echo "✅ All streamable-http->STDIO transport tests passed!"
+          exit 0
diff --git a/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/mcpserver.yaml b/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio-streamable-http/mcpserver.yaml
@@ -0,0 +1,20 @@
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPServer
+metadata:
+  name: yardstick
+  namespace: test-namespace
+spec:
+  image: ghcr.io/stackloklabs/yardstick/yardstick-server:0.0.2
+  transport: stdio
+  proxyMode: streamable-http
+  proxyPort: 8080
+  permissionProfile:
+    type: builtin
+    name: network
+  resources:
+    limits:
+      cpu: "100m"
+      memory: "128Mi"
+    requests:
+      cpu: "50m"
+      memory: "64Mi"
diff --git a/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio/mcpserver.yaml b/test/e2e/chainsaw/operator/multi-tenancy/test-scenarios/stdio/mcpserver.yaml
@@ -6,6 +6,7 @@ metadata:
 spec:
   image: ghcr.io/stackloklabs/yardstick/yardstick-server:0.0.2
   transport: stdio
+  proxyMode: sse
   proxyPort: 8080
   permissionProfile:
     type: builtin
diff --git a/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-pod-running.yaml b/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-pod-running.yaml
@@ -0,0 +1,7 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: yardstick
+  namespace: toolhive-system
+status:
+  availableReplicas: 1
diff --git a/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-proxy-runner-running.yaml b/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-proxy-runner-running.yaml
@@ -0,0 +1,17 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: yardstick
+  namespace: toolhive-system
+spec:
+  replicas: 1
+status:
+  # Ensure deployment is available and progressing successfully
+  (conditions[?type == 'Available'] | [0].status): "True"
+  (conditions[?type == 'Progressing'] | [0].status): "True"
+  (conditions[?type == 'Progressing'] | [0].reason): "NewReplicaSetAvailable"
+  # Ensure all replicas are ready and available
+  replicas: 1
+  readyReplicas: 1
+  availableReplicas: 1
+  updatedReplicas: 1
diff --git a/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-proxy-runner-svc.yaml b/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-proxy-runner-svc.yaml
@@ -0,0 +1,5 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: mcp-yardstick-proxy
+  namespace: toolhive-system
diff --git a/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-running.yaml b/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/assert-mcpserver-running.yaml
@@ -0,0 +1,8 @@
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPServer
+metadata:
+  name: yardstick
+  namespace: toolhive-system
+status:
+  message: "MCP server is running"
+  phase: "Running"
diff --git a/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/chainsaw-test.yaml b/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/chainsaw-test.yaml
diff --git a/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/mcpserver.yaml b/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio-streamable-http/mcpserver.yaml
diff --git a/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio/mcpserver.yaml b/test/e2e/chainsaw/operator/single-tenancy/test-scenarios/stdio/mcpserver.yaml

Original file line number	Diff line number	Diff line change
`@@ -123,7 +123,7 @@ func (r MCPServerReconciler) createRunConfigFromMCPServer(m mcpv1alpha1.MCPSer`
`123`	`123`
`124`	`124`	`proxyMode := m.Spec.ProxyMode`
`125`	`125`	`if proxyMode == "" {`
`126`		`- proxyMode = "sse" // Default to SSE for backward compatibility`
	`126`	`+ proxyMode = "streamable-http" // Default to streamable-http (SSE is deprecated)`
`127`	`127`	`}`
`128`	`128`
`129`	`129`	`options := []runner.RunConfigBuilderOption{`