Operator: Change default proxy mode from deprecated SSE to streaming-http

[JAORMX]

Problem

The ToolHive Kubernetes Operator currently defaults to using the SSE (Server-Sent Events) transport for proxying MCP servers. However, the SSE transport is deprecated in favor of the newer streaming-http transport (also referred to as streamable-http in the codebase).

According to the MCP specification, the streaming-http transport is the recommended approach for HTTP-based MCP communication.

Current Behavior

The default proxy mode is set to SSE in two locations in the operator:

1. Operator Controller (cmd/thv-operator/controllers/mcpserver_runconfig.go:257):

   proxyMode := m.Spec.ProxyMode
   if proxyMode == "" {
       proxyMode = "sse" // Default to SSE for backward compatibility
   }

2. CRD Definition (cmd/thv-operator/api/v1alpha1/mcpserver_types.go:36-41):

   // 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
   // +optional
   ProxyMode string `json:"proxyMode,omitempty"`

Expected Behavior

The default proxy mode should be streamable-http instead of sse to align with:

• Modern MCP specification recommendations
• The deprecation of the SSE transport
• Better performance and reliability characteristics of streaming-http

Proposed Solution

Change the default proxy mode from sse to streamable-http in both locations:

1. Update cmd/thv-operator/controllers/mcpserver_runconfig.go:257:

   proxyMode := m.Spec.ProxyMode
   if proxyMode == "" {
       proxyMode = "streamable-http" // Default to streamable-http (SSE is deprecated)
   }

2. Update cmd/thv-operator/api/v1alpha1/mcpserver_types.go:39:

   // 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=streamable-http
   // +optional
   ProxyMode string `json:"proxyMode,omitempty"`

3. Update test expectations in cmd/thv-operator/controllers/mcpserver_runconfig_test.go:205:

   assert.Equal(t, transporttypes.ProxyModeStreamableHTTP, config.ProxyMode, "Should default to streamable-http")

Required Follow-up Tasks

After modifying the CRD, you must run the following commands (as per cmd/thv-operator/CLAUDE.md):

task operator-generate
task operator-manifests
cd cmd/thv-operator && task crdref-gen

Important: Since this is a CRD change, you must also bump the CRD Helm chart version according to the instructions in deploy/charts/operator-crds/CLAUDE.md.

Impact

• Breaking change: Users relying on the default SSE behavior will need to explicitly specify proxyMode: sse in their MCPServer resources
• Migration path: Users can explicitly set proxyMode: sse in their MCPServer specs during the transition period
• Benefits:
  • Better alignment with MCP specification
  • Improved performance and reliability
  • Future-proofing as SSE support may be removed

Additional Context

The codebase already has full support for streaming-http transport:

• Transport type defined: types.TransportTypeStreamableHTTP
• Proxy mode defined: types.ProxyModeStreamableHTTP
• Implementation: pkg/transport/proxy/streamable/
• Tests: Multiple e2e tests for streamable-http transport

Related

• Change default proxy mode from deprecated SSE to streaming-http #2210 - CLI/API default proxy mode change

[heart-reburn]

I would love to work on it.

[JAORMX]

@heart-reburn sounds good! Thanks for volunteering!