Deprecate SSE proxy mode for stdio transport (#3008)

Add deprecation notices for the SSE proxy mode which will be removed
  in a future release. Users should migrate to streamable-http (now the
  default).

  Changes:
  - Add runtime warning when --proxy-mode sse is explicitly used
  - Update help text to indicate SSE is deprecated
  - Add Deprecated comment to ProxyModeSSE constant
  - Update CLI, CRD, and API documentation
  - Extract sseSuffix constant in inspector.go to satisfy linter

Signed-off-by: carlos <[email protected]>

Author: carlos-gn

cmd/thv/app/inspector.go

@@ -22,6 +22,8 @@ import (
 	"github.com/stacklok/toolhive/pkg/workloads"
 )
 
+const sseSuffix = "sse"
+
 var (
 	inspectorUIPort       int
 	inspectorMCPProxyPort int
@@ -163,8 +165,8 @@ func inspectorCmdFunc(cmd *cobra.Command, args []string) error {
 		var suffix string
 		var transportTypeStr string
 		if transportType == types.TransportTypeSSE || transportType == types.TransportTypeStdio {
-			suffix = "sse"
-			transportTypeStr = "sse"
+			suffix = sseSuffix
+			transportTypeStr = sseSuffix
 		} else {
 			suffix = "mcp"
 			transportTypeStr = "streamable-http"

cmd/thv/app/run.go

@@ -496,5 +496,12 @@ func validateRunFlags(cmd *cobra.Command, args []string) error {
 		}
 	}
 
+	// Show deprecation warning if --proxy-mode is explicitly set to SSE
+	proxyModeFlag := cmd.Flags().Lookup("proxy-mode")
+	if proxyModeFlag != nil && proxyModeFlag.Changed && proxyModeFlag.Value.String() == "sse" {
+		logger.Warn("The 'sse' proxy mode is deprecated and will be removed in a future release. " +
+			"Please migrate to 'streamable-http' (the new default).")
+	}
+
 	return nil
 }

cmd/thv/app/run_flags.go

@@ -123,7 +123,10 @@ type RunFlags struct {
 // AddRunFlags adds all the run flags to a command
 func AddRunFlags(cmd *cobra.Command, config *RunFlags) {
 	cmd.Flags().StringVar(&config.Transport, "transport", "", "Transport mode (sse, streamable-http or stdio)")
-	cmd.Flags().StringVar(&config.ProxyMode, "proxy-mode", "streamable-http", "Proxy mode for stdio (streamable-http or sse)")
+	cmd.Flags().StringVar(&config.ProxyMode,
+		"proxy-mode",
+		"streamable-http",
+		"Proxy mode for stdio (streamable-http or sse (deprecated, will be removed))")
 	cmd.Flags().StringVar(&config.Name, "name", "", "Name of the MCP server (auto-generated from image if not provided)")
 	cmd.Flags().StringVar(&config.Group, "group", "default",
 		"Name of the group this workload belongs to (defaults to 'default' if not specified)")

docs/cli/thv_run.md

@@ -140,6 +140,7 @@ type RunConfig struct {
 	TrustProxyHeaders bool `json:"trust_proxy_headers,omitempty" yaml:"trust_proxy_headers,omitempty"`
 
 	// ProxyMode is the proxy mode for stdio transport ("sse" or "streamable-http")
+	// Note: "sse" is deprecated; use "streamable-http" instead.
 	ProxyMode types.ProxyMode `json:"proxy_mode,omitempty" yaml:"proxy_mode,omitempty"`
 
 	// ThvCABundle is the path to the CA certificate bundle for ToolHive HTTP operations

docs/server/docs.go

@@ -211,6 +211,8 @@ type ProxyMode string
 
 const (
 	// ProxyModeSSE is the proxy mode for SSE.
+	// Deprecated: SSE proxy mode is deprecated and will be removed in a future release.
+	// Use ProxyModeStreamableHTTP instead.
 	ProxyModeSSE ProxyMode = "sse"
 	// ProxyModeStreamableHTTP is the proxy mode for streamable HTTP.
 	ProxyModeStreamableHTTP ProxyMode = "streamable-http"