Normalize proxyMode to always reflect effective HTTP protocol

proxyMode was only meaningful for stdio transports but could be set on
any transport, returning empty or misleading values to clients. This
caused confusion and required every client to implement conditional
logic via GetEffectiveProxyMode() to determine the actual protocol.

Add EffectiveProxyMode() to pkg/transport/types as the canonical typed
implementation, and NormalizeProxyMode() on RunConfig to apply it at
creation and load time. This ensures proxyMode is always the effective
value in persisted configs and API responses.

Also fixes the conflicting default in StdioTransport (SSE vs
streamable-http everywhere else).

Fixes #3296

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ChrisJBurns

pkg/export/k8s.go

@@ -88,7 +88,7 @@ func runConfigToMCPServer(config *runner.RunConfig) (*v1alpha1.MCPServer, error)
 	}
 
 	// Set proxy mode if transport is stdio
-	if config.Transport == types.TransportTypeStdio && config.ProxyMode != "" {
+	if config.Transport == types.TransportTypeStdio {
 		mcpServer.Spec.ProxyMode = string(config.ProxyMode)
 	}
 

pkg/runner/config.go

@@ -171,7 +171,9 @@ type RunConfig struct {
 	// TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies
 	TrustProxyHeaders bool `json:"trust_proxy_headers,omitempty" yaml:"trust_proxy_headers,omitempty"`
 
-	// ProxyMode is the proxy mode for stdio transport ("sse" or "streamable-http")
+	// ProxyMode is the effective HTTP protocol the proxy uses.
+	// For stdio transports, this is the configured mode (sse or streamable-http).
+	// For direct transports (sse/streamable-http), this matches the transport type.
 	// Note: "sse" is deprecated; use "streamable-http" instead.
 	ProxyMode types.ProxyMode `json:"proxy_mode,omitempty" yaml:"proxy_mode,omitempty" enums:"sse,streamable-http"`
 
@@ -261,6 +263,12 @@ type SessionRedisConfig struct {
 	KeyPrefix string `json:"key_prefix,omitempty" yaml:"key_prefix,omitempty"`
 }
 
+// NormalizeProxyMode sets ProxyMode to the effective value based on the
+// transport type, so downstream readers always see the actual HTTP protocol.
+func (c *RunConfig) NormalizeProxyMode() {
+	c.ProxyMode = types.EffectiveProxyMode(c.Transport, c.ProxyMode)
+}
+
 // WriteJSON serializes the RunConfig to JSON and writes it to the provided writer
 func (c *RunConfig) WriteJSON(w io.Writer) error {
 	// Ensure the schema version is set
@@ -313,6 +321,9 @@ func ReadJSON(r io.Reader) (*RunConfig, error) {
 		return nil, fmt.Errorf("failed to migrate bearer token: %w", err)
 	}
 
+	// Normalize proxyMode so pre-existing configs always reflect the effective protocol
+	config.NormalizeProxyMode()
+
 	return &config, nil
 }
 

pkg/runner/config_builder.go

@@ -837,6 +837,9 @@ func internalRunConfigBuilder(
 	// Set schema version.
 	b.config.SchemaVersion = CurrentSchemaVersion
 
+	// Normalize proxyMode to the effective value before returning.
+	b.config.NormalizeProxyMode()
+
 	return b.config, nil
 }
 

pkg/runner/config_test.go

@@ -95,6 +95,81 @@ func TestRunConfig_WithTransport(t *testing.T) {
 	}
 }
 
+func TestRunConfig_NormalizeProxyMode(t *testing.T) {
+	t.Parallel()
+
+	testCases := []struct {
+		name     string
+		config   *RunConfig
+		expected types.ProxyMode
+	}{
+		{
+			name: "stdio with empty proxy mode defaults to streamable-http",
+			config: &RunConfig{
+				Transport: types.TransportTypeStdio,
+				ProxyMode: "",
+			},
+			expected: types.ProxyModeStreamableHTTP,
+		},
+		{
+			name: "stdio with sse proxy mode stays sse",
+			config: &RunConfig{
+				Transport: types.TransportTypeStdio,
+				ProxyMode: types.ProxyModeSSE,
+			},
+			expected: types.ProxyModeSSE,
+		},
+		{
+			name: "stdio with streamable-http proxy mode stays streamable-http",
+			config: &RunConfig{
+				Transport: types.TransportTypeStdio,
+				ProxyMode: types.ProxyModeStreamableHTTP,
+			},
+			expected: types.ProxyModeStreamableHTTP,
+		},
+		{
+			name: "sse transport with empty proxy mode becomes sse",
+			config: &RunConfig{
+				Transport: types.TransportTypeSSE,
+				ProxyMode: "",
+			},
+			expected: types.ProxyMode("sse"),
+		},
+		{
+			name: "sse transport with streamable-http proxy mode becomes sse",
+			config: &RunConfig{
+				Transport: types.TransportTypeSSE,
+				ProxyMode: types.ProxyModeStreamableHTTP,
+			},
+			expected: types.ProxyMode("sse"),
+		},
+		{
+			name: "streamable-http transport with empty proxy mode becomes streamable-http",
+			config: &RunConfig{
+				Transport: types.TransportTypeStreamableHTTP,
+				ProxyMode: "",
+			},
+			expected: types.ProxyMode("streamable-http"),
+		},
+		{
+			name: "streamable-http transport with sse proxy mode becomes streamable-http",
+			config: &RunConfig{
+				Transport: types.TransportTypeStreamableHTTP,
+				ProxyMode: types.ProxyModeSSE,
+			},
+			expected: types.ProxyMode("streamable-http"),
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			tc.config.NormalizeProxyMode()
+			assert.Equal(t, tc.expected, tc.config.ProxyMode)
+		})
+	}
+}
+
 // TestRunConfig_WithPorts tests the WithPorts method
 // Note: This test uses actual port finding logic, so it may fail if ports are in use
 func TestRunConfig_WithPorts(t *testing.T) {

pkg/transport/stdio.go

@@ -125,7 +125,7 @@ func NewStdioTransport(
 		middlewares:       middlewares,
 		prometheusHandler: prometheusHandler,
 		shutdownCh:        make(chan struct{}),
-		proxyMode:         types.ProxyModeSSE, // default to SSE for backward compatibility
+		proxyMode:         types.ProxyModeStreamableHTTP, // default to streamable-http
 		retryConfig:       defaultRetryConfig(),
 	}
 }

pkg/transport/types/transport.go

@@ -286,3 +286,17 @@ func IsValidProxyMode(mode string) bool {
 func (p ProxyMode) String() string {
 	return string(p)
 }
+
+// EffectiveProxyMode determines the actual HTTP protocol the proxy is using.
+// For stdio transports, this returns the proxy mode (sse or streamable-http).
+// For direct transports (sse/streamable-http), this returns the transport type
+// since the transport itself is the protocol.
+func EffectiveProxyMode(transportType TransportType, proxyMode ProxyMode) ProxyMode {
+	if transportType == TransportTypeStdio {
+		if proxyMode == "" {
+			return ProxyModeStreamableHTTP
+		}
+		return proxyMode
+	}
+	return ProxyMode(transportType.String())
+}

pkg/transport/types/transport_test.go

@@ -159,6 +159,86 @@ func TestTransportTypeConstants(t *testing.T) {
 	assert.Equal(t, "inspector", string(TransportTypeInspector))
 }
 
+func TestEffectiveProxyMode(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		transport TransportType
+		proxyMode ProxyMode
+		expected  ProxyMode
+	}{
+		{
+			name:      "stdio with sse proxy mode returns sse",
+			transport: TransportTypeStdio,
+			proxyMode: ProxyModeSSE,
+			expected:  ProxyModeSSE,
+		},
+		{
+			name:      "stdio with streamable-http proxy mode returns streamable-http",
+			transport: TransportTypeStdio,
+			proxyMode: ProxyModeStreamableHTTP,
+			expected:  ProxyModeStreamableHTTP,
+		},
+		{
+			name:      "stdio with empty proxy mode defaults to streamable-http",
+			transport: TransportTypeStdio,
+			proxyMode: "",
+			expected:  ProxyModeStreamableHTTP,
+		},
+		{
+			name:      "sse transport with empty proxy mode returns sse",
+			transport: TransportTypeSSE,
+			proxyMode: "",
+			expected:  ProxyMode("sse"),
+		},
+		{
+			name:      "sse transport with sse proxy mode returns sse",
+			transport: TransportTypeSSE,
+			proxyMode: ProxyModeSSE,
+			expected:  ProxyMode("sse"),
+		},
+		{
+			name:      "sse transport with streamable-http proxy mode returns sse",
+			transport: TransportTypeSSE,
+			proxyMode: ProxyModeStreamableHTTP,
+			expected:  ProxyMode("sse"),
+		},
+		{
+			name:      "streamable-http transport with empty proxy mode returns streamable-http",
+			transport: TransportTypeStreamableHTTP,
+			proxyMode: "",
+			expected:  ProxyMode("streamable-http"),
+		},
+		{
+			name:      "streamable-http transport with sse proxy mode returns streamable-http",
+			transport: TransportTypeStreamableHTTP,
+			proxyMode: ProxyModeSSE,
+			expected:  ProxyMode("streamable-http"),
+		},
+		{
+			name:      "streamable-http transport with streamable-http proxy mode returns streamable-http",
+			transport: TransportTypeStreamableHTTP,
+			proxyMode: ProxyModeStreamableHTTP,
+			expected:  ProxyMode("streamable-http"),
+		},
+		{
+			name:      "inspector transport with empty proxy mode returns inspector",
+			transport: TransportTypeInspector,
+			proxyMode: "",
+			expected:  ProxyMode("inspector"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			result := EffectiveProxyMode(tt.transport, tt.proxyMode)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
 func TestTransportType_RoundTrip(t *testing.T) {
 	t.Parallel()
 

pkg/workloads/types/types.go

@@ -126,18 +126,11 @@ func WorkloadFromContainerInfo(container *runtime.ContainerInfo, runConfigStore
 	}, nil
 }
 
-// GetEffectiveProxyMode determines the effective proxy mode that clients should use
-// For stdio transports, this returns the proxy mode (sse or streamable-http)
-// For direct transports (sse/streamable-http), this returns the transport type as the proxy mode
+// GetEffectiveProxyMode determines the effective proxy mode that clients should use.
+// For stdio transports, this returns the proxy mode (sse or streamable-http).
+// For direct transports (sse/streamable-http), this returns the transport type as the proxy mode.
+//
+// Prefer types.EffectiveProxyMode for new code operating on typed values.
 func GetEffectiveProxyMode(transportType types.TransportType, proxyMode string) string {
-	// If the underlying transport is stdio, return the proxy mode (could be empty)
-	if transportType == types.TransportTypeStdio {
-		if proxyMode == "" {
-			return types.ProxyModeStreamableHTTP.String()
-		}
-		return proxyMode
-	}
-
-	// For direct transports (sse, streamable-http), return the transport type as the proxy mode
-	return transportType.String()
+	return types.EffectiveProxyMode(transportType, types.ProxyMode(proxyMode)).String()
 }