Deprecate SSE proxy mode for stdio transport

[amirejaz]

Summary

Deprecate the SSE (Server-Sent Events) proxy mode for stdio transport in favor of streamable-http, which is the recommended MCP transport.

Background

The MCP specification has deprecated SSE transport in favor of streamable-http. While ToolHive currently supports both SSE and streamable-http proxy modes for stdio transport, we should deprecate the SSE proxy mode to align with the specification and reduce maintenance burden.

Current State

• ✅ The CLI (thv run) defaults to streamable-http for --proxy-mode flag
• ✅ The operator defaults to streamable-http for stdio transport
• SSE proxy implementation exists in pkg/transport/proxy/httpsse/http_proxy.go
• Tests and documentation still reference SSE proxy mode

Proposed Deprecation Plan

1. Phase 1: Deprecation Notice

   • Add deprecation warnings when SSE proxy mode is explicitly used
   • Update documentation to mark SSE proxy mode as deprecated
   • Update code comments to indicate deprecation
   • Update help text for --proxy-mode flag to indicate SSE is deprecated

2. Phase 2: Removal (Future)

   • Remove SSE proxy mode support after a deprecation period
   • Remove pkg/transport/proxy/httpsse/ package
   • Clean up related code and tests
   • Remove --proxy-mode flag entirely since there will only be one option (streamable-http)

Decision: Keep --proxy-mode Flag During Deprecation

Recommendation: Keep the flag during deprecation, then remove it after SSE support is removed.

Implementation during deprecation:

• Keep the flag but show deprecation warnings when --proxy-mode sse is used
• Default to streamable-http (already done)
• Make the flag optional (already done)
• Update help text to indicate SSE is deprecated

After SSE removal:

• Remove the flag entirely since there will only be one option
• Simplify code by removing proxy mode selection logic

Migration Path

Users currently using SSE proxy mode should:

• Update their configurations to use --proxy-mode streamable-http (or proxyMode: streamable-http in operator configs)
• Update any scripts or automation that explicitly set SSE proxy mode
• Expect deprecation warnings if they continue using --proxy-mode sse during the deprecation period

Related Code

• pkg/transport/stdio.go - Stdio transport implementation (defaults to ProxyModeStreamableHTTP)
• pkg/transport/proxy/httpsse/http_proxy.go - SSE proxy implementation (to be removed)
• pkg/transport/types/transport.go - Proxy mode type definitions
• cmd/thv/app/run_flags.go:126 - CLI flag defaults to streamable-http
• cmd/thv-operator/controllers/mcpserver_runconfig.go:126 - Operator defaults to streamable-http
• pkg/transport/factory.go:51 - Factory sets proxy mode on stdio transport

References

• MCP Specification - Streamable HTTP
• Documentation: docs/arch/03-transport-architecture.md (notes SSE is deprecated)