Feat: Impl Server-Side Streamable HTTP transport (#273)

* Create logger.go

* remove duplicated key

* impl streamable http server

* update

* Update streamable_http.go

* update protocol version

* use HTTPContextFunc

* impl SessionWithTools for sessions

* rename

* rename

* add more validation

* fix

* add test

* ut

* Update http_transport_options.go

* Update streamable_http.go

* doc

* doc

* remove shared options for sse

* doc

* doc

* ut

* fix race

* ut

* doc

* fix

* Update README.md

* Update streamable_http.go

* update demo

* fix compile

* fix lint

---------

Co-authored-by: gaoji <gaoji@bytedance.com>

Author: leavez

README.md

@@ -531,6 +531,10 @@ For examples, see the `examples/` directory.
 
 ## Extras
 
+### Transports
+
+MCP-Go supports stdio, SSE and streamable-HTTP transport layers.
+
 ### Session Management
 
 MCP-Go provides a robust session management system that allows you to:

client/transport/streamable_http.go

@@ -127,7 +127,6 @@ func (c *StreamableHTTP) Close() error {
 }
 
 const (
-	initializeMethod   = "initialize"
 	headerKeySessionID = "Mcp-Session-Id"
 )
 
@@ -198,7 +197,7 @@ func (c *StreamableHTTP) SendRequest(
 		return nil, fmt.Errorf("request failed with status %d: %s", resp.StatusCode, body)
 	}
 
-	if request.Method == initializeMethod {
+	if request.Method == string(mcp.MethodInitialize) {
 		// saved the received session ID in the response
 		// empty session ID is allowed
 		if sessionID := resp.Header.Get(headerKeySessionID); sessionID != "" {

examples/custom_context/main.go

@@ -122,9 +122,8 @@ func NewMCPServer() *MCPServer {
 	}
 }
 
-func (s *MCPServer) ServeSSE(addr string) *server.SSEServer {
-	return server.NewSSEServer(s.server,
-		server.WithBaseURL(fmt.Sprintf("http://%s", addr)),
+func (s *MCPServer) ServeHTTP() *server.StreamableHTTPServer {
+	return server.NewStreamableHTTPServer(s.server,
 		server.WithHTTPContextFunc(authFromRequest),
 	)
 }
@@ -135,12 +134,12 @@ func (s *MCPServer) ServeStdio() error {
 
 func main() {
 	var transport string
-	flag.StringVar(&transport, "t", "stdio", "Transport type (stdio or sse)")
+	flag.StringVar(&transport, "t", "stdio", "Transport type (stdio or http)")
 	flag.StringVar(
 		&transport,
 		"transport",
 		"stdio",
-		"Transport type (stdio or sse)",
+		"Transport type (stdio or http)",
 	)
 	flag.Parse()
 
@@ -151,15 +150,15 @@ func main() {
 		if err := s.ServeStdio(); err != nil {
 			log.Fatalf("Server error: %v", err)
 		}
-	case "sse":
-		sseServer := s.ServeSSE("localhost:8080")
-		log.Printf("SSE server listening on :8080")
-		if err := sseServer.Start(":8080"); err != nil {
+	case "http":
+		httpServer := s.ServeHTTP()
+		log.Printf("HTTP server listening on :8080")
+		if err := httpServer.Start(":8080"); err != nil {
 			log.Fatalf("Server error: %v", err)
 		}
 	default:
 		log.Fatalf(
-			"Invalid transport type: %s. Must be 'stdio' or 'sse'",
+			"Invalid transport type: %s. Must be 'stdio' or 'http'",
 			transport,
 		)
 	}

examples/everything/main.go

@@ -475,17 +475,17 @@ func handleNotification(
 
 func main() {
 	var transport string
-	flag.StringVar(&transport, "t", "stdio", "Transport type (stdio or sse)")
-	flag.StringVar(&transport, "transport", "stdio", "Transport type (stdio or sse)")
+	flag.StringVar(&transport, "t", "stdio", "Transport type (stdio or http)")
+	flag.StringVar(&transport, "transport", "stdio", "Transport type (stdio or http)")
 	flag.Parse()
 
 	mcpServer := NewMCPServer()
 
-	// Only check for "sse" since stdio is the default
-	if transport == "sse" {
-		sseServer := server.NewSSEServer(mcpServer, server.WithBaseURL("http://localhost:8080"))
-		log.Printf("SSE server listening on :8080")
-		if err := sseServer.Start(":8080"); err != nil {
+	// Only check for "http" since stdio is the default
+	if transport == "http" {
+		httpServer := server.NewStreamableHTTPServer(mcpServer)
+		log.Printf("HTTP server listening on :8080/mcp")
+		if err := httpServer.Start(":8080"); err != nil {
 			log.Fatalf("Server error: %v", err)
 		}
 	} else {

examples/simple_client/main.go

@@ -17,12 +17,12 @@ import (
 func main() {
 	// Define command line flags
 	stdioCmd := flag.String("stdio", "", "Command to execute for stdio transport (e.g. 'python server.py')")
-	sseURL := flag.String("sse", "", "URL for SSE transport (e.g. 'http://localhost:8080/sse')")
+	httpURL := flag.String("http", "", "URL for HTTP transport (e.g. 'http://localhost:8080/mcp')")
 	flag.Parse()
 
 	// Validate flags
-	if (*stdioCmd == "" && *sseURL == "") || (*stdioCmd != "" && *sseURL != "") {
-		fmt.Println("Error: You must specify exactly one of --stdio or --sse")
+	if (*stdioCmd == "" && *httpURL == "") || (*stdioCmd != "" && *httpURL != "") {
+		fmt.Println("Error: You must specify exactly one of --stdio or --http")
 		flag.Usage()
 		os.Exit(1)
 	}
@@ -51,11 +51,6 @@ func main() {
 		// Create stdio transport with verbose logging
 		stdioTransport := transport.NewStdio(command, nil, cmdArgs...)
 
-		// Start the transport
-		if err := stdioTransport.Start(ctx); err != nil {
-			log.Fatalf("Failed to start stdio transport: %v", err)
-		}
-
 		// Create client with the transport
 		c = client.NewClient(stdioTransport)
 
@@ -78,20 +73,20 @@ func main() {
 			}()
 		}
 	} else {
-		fmt.Println("Initializing SSE client...")
-		// Create SSE transport
-		sseTransport, err := transport.NewSSE(*sseURL)
+		fmt.Println("Initializing HTTP client...")
+		// Create HTTP transport
+		httpTransport, err := transport.NewStreamableHTTP(*httpURL)
 		if err != nil {
-			log.Fatalf("Failed to create SSE transport: %v", err)
-		}
-
-		// Start the transport
-		if err := sseTransport.Start(ctx); err != nil {
-			log.Fatalf("Failed to start SSE transport: %v", err)
+			log.Fatalf("Failed to create HTTP transport: %v", err)
 		}
 
 		// Create client with the transport
-		c = client.NewClient(sseTransport)
+		c = client.NewClient(httpTransport)
+	}
+
+	// Start the client 
+	if err := c.Start(ctx); err != nil {
+		log.Fatalf("Failed to start client: %v", err)
 	}
 
 	// Set up notification handler

mcp/types.go

@@ -96,7 +96,7 @@ func (t *URITemplate) UnmarshalJSON(data []byte) error {
 type JSONRPCMessage any
 
 // LATEST_PROTOCOL_VERSION is the most recent version of the MCP protocol.
-const LATEST_PROTOCOL_VERSION = "2024-11-05"
+const LATEST_PROTOCOL_VERSION = "2025-03-26"
 
 // JSONRPC_VERSION is the version of JSON-RPC used by MCP.
 const JSONRPC_VERSION = "2.0"

server/http_transport_options.go

@@ -3,187 +3,9 @@ package server
 import (
 	"context"
 	"net/http"
-	"net/url"
-	"strings"
-	"time"
 )
 
 // HTTPContextFunc is a function that takes an existing context and the current
 // request and returns a potentially modified context based on the request
 // content. This can be used to inject context values from headers, for example.
 type HTTPContextFunc func(ctx context.Context, r *http.Request) context.Context
-
-// httpTransportConfigurable is an internal interface for shared HTTP transport configuration.
-type httpTransportConfigurable interface {
-	setBasePath(string)
-	setDynamicBasePath(DynamicBasePathFunc)
-	setKeepAliveInterval(time.Duration)
-	setKeepAlive(bool)
-	setContextFunc(HTTPContextFunc)
-	setHTTPServer(*http.Server)
-	setBaseURL(string)
-}
-
-// HTTPTransportOption is a function that configures an httpTransportConfigurable.
-type HTTPTransportOption func(httpTransportConfigurable)
-
-// Option interfaces and wrappers for server configuration
-// Base option interface
-type HTTPServerOption interface {
-	isHTTPServerOption()
-}
-
-// SSE-specific option interface
-type SSEOption interface {
-	HTTPServerOption
-	applyToSSE(*SSEServer)
-}
-
-// StreamableHTTP-specific option interface
-type StreamableHTTPOption interface {
-	HTTPServerOption
-	applyToStreamableHTTP(*StreamableHTTPServer)
-}
-
-// Common options that work with both server types
-type CommonHTTPServerOption interface {
-	SSEOption
-	StreamableHTTPOption
-}
-
-// Wrapper for SSE-specific functional options
-type sseOption func(*SSEServer)
-
-func (o sseOption) isHTTPServerOption()     {}
-func (o sseOption) applyToSSE(s *SSEServer) { o(s) }
-
-// Wrapper for StreamableHTTP-specific functional options
-type streamableHTTPOption func(*StreamableHTTPServer)
-
-func (o streamableHTTPOption) isHTTPServerOption()                           {}
-func (o streamableHTTPOption) applyToStreamableHTTP(s *StreamableHTTPServer) { o(s) }
-
-// Refactor commonOption to use a single apply func(httpTransportConfigurable)
-type commonOption struct {
-	apply func(httpTransportConfigurable)
-}
-
-func (o commonOption) isHTTPServerOption()                           {}
-func (o commonOption) applyToSSE(s *SSEServer)                       { o.apply(s) }
-func (o commonOption) applyToStreamableHTTP(s *StreamableHTTPServer) { o.apply(s) }
-
-// TODO: This is a stub implementation of StreamableHTTPServer just to show how
-// to use it with the new options interfaces.
-type StreamableHTTPServer struct{}
-
-// Add stub methods to satisfy httpTransportConfigurable
-
-func (s *StreamableHTTPServer) setBasePath(string)                     {}
-func (s *StreamableHTTPServer) setDynamicBasePath(DynamicBasePathFunc) {}
-func (s *StreamableHTTPServer) setKeepAliveInterval(time.Duration)     {}
-func (s *StreamableHTTPServer) setKeepAlive(bool)                      {}
-func (s *StreamableHTTPServer) setContextFunc(HTTPContextFunc)         {}
-func (s *StreamableHTTPServer) setHTTPServer(srv *http.Server)         {}
-func (s *StreamableHTTPServer) setBaseURL(baseURL string)              {}
-
-// Ensure the option types implement the correct interfaces
-var (
-	_ httpTransportConfigurable = (*StreamableHTTPServer)(nil)
-	_ SSEOption                 = sseOption(nil)
-	_ StreamableHTTPOption      = streamableHTTPOption(nil)
-	_ CommonHTTPServerOption    = commonOption{}
-)
-
-// WithStaticBasePath adds a new option for setting a static base path.
-// This is useful for mounting the server at a known, fixed path.
-func WithStaticBasePath(basePath string) CommonHTTPServerOption {
-	return commonOption{
-		apply: func(c httpTransportConfigurable) {
-			c.setBasePath(basePath)
-		},
-	}
-}
-
-// DynamicBasePathFunc allows the user to provide a function to generate the
-// base path for a given request and sessionID. This is useful for cases where
-// the base path is not known at the time of SSE server creation, such as when
-// using a reverse proxy or when the base path is dynamically generated. The
-// function should return the base path (e.g., "/mcp/tenant123").
-type DynamicBasePathFunc func(r *http.Request, sessionID string) string
-
-// WithDynamicBasePath accepts a function for generating the base path.
-// This is useful for cases where the base path is not known at the time of server creation,
-// such as when using a reverse proxy or when the server is mounted at a dynamic path.
-func WithDynamicBasePath(fn DynamicBasePathFunc) CommonHTTPServerOption {
-	return commonOption{
-		apply: func(c httpTransportConfigurable) {
-			c.setDynamicBasePath(fn)
-		},
-	}
-}
-
-// WithKeepAliveInterval sets the keep-alive interval for the transport.
-// When enabled, the server will periodically send ping events to keep the connection alive.
-func WithKeepAliveInterval(interval time.Duration) CommonHTTPServerOption {
-	return commonOption{
-		apply: func(c httpTransportConfigurable) {
-			c.setKeepAliveInterval(interval)
-		},
-	}
-}
-
-// WithKeepAlive enables or disables keep-alive for the transport.
-// When enabled, the server will send periodic keep-alive events to clients.
-func WithKeepAlive(keepAlive bool) CommonHTTPServerOption {
-	return commonOption{
-		apply: func(c httpTransportConfigurable) {
-			c.setKeepAlive(keepAlive)
-		},
-	}
-}
-
-// WithHTTPContextFunc sets a function that will be called to customize the context
-// for the server using the incoming request. This is useful for injecting
-// context values from headers or other request properties.
-func WithHTTPContextFunc(fn HTTPContextFunc) CommonHTTPServerOption {
-	return commonOption{
-		apply: func(c httpTransportConfigurable) {
-			c.setContextFunc(fn)
-		},
-	}
-}
-
-// WithBaseURL sets the base URL for the HTTP transport server.
-// This is useful for configuring the externally visible base URL for clients.
-func WithBaseURL(baseURL string) CommonHTTPServerOption {
-	return commonOption{
-		apply: func(c httpTransportConfigurable) {
-			if baseURL != "" {
-				u, err := url.Parse(baseURL)
-				if err != nil {
-					return
-				}
-				if u.Scheme != "http" && u.Scheme != "https" {
-					return
-				}
-				if u.Host == "" || strings.HasPrefix(u.Host, ":") {
-					return
-				}
-				if len(u.Query()) > 0 {
-					return
-				}
-			}
-			c.setBaseURL(strings.TrimSuffix(baseURL, "/"))
-		},
-	}
-}
-
-// WithHTTPServer sets the HTTP server instance for the transport.
-// This is useful for advanced scenarios where you want to provide your own http.Server.
-func WithHTTPServer(srv *http.Server) CommonHTTPServerOption {
-	return commonOption{
-		apply: func(c httpTransportConfigurable) {
-			c.setHTTPServer(srv)
-		},
-	}
-}