feat(server/sse): Add support for dynamic base paths (#214)

* feat!(server/sse): Add support for dynamic base paths

This change introduces the ability to mount SSE endpoints at dynamic
paths with variable segments (e.g., `/api/{tenant}/sse`) by adding a new
`WithDynamicBasePath` option and related functionality. This enables
advanced use cases such as multi-tenant architectures or integration
with routers that support path parameters.

Key Features:

* DynamicBasePathFunc: New function type and option
  (WithDynamicBasePath) to generate the SSE server's base path
  dynamically per request/session.
* Flexible Routing: New SSEHandler() and MessageHandler() methods allow
  mounting handlers at arbitrary or dynamic paths using any router
  (e.g., net/http, chi, gorilla/mux).
* Endpoint Generation: GetMessageEndpointForClient now supports both
  static and dynamic path modes, and correctly generates full URLs when
  configured.
* Example: Added examples/dynamic_path/main.go demonstrating dynamic
  path mounting and usage.

```go
mcpServer := mcp.NewMCPServer("dynamic-path-example", "1.0.0")
sseServer := mcp.NewSSEServer(
  mcpServer,
  mcp.WithDynamicBasePath(func(r *http.Request, sessionID string) string {
    tenant := r.PathValue("tenant")
    return "/api/" + tenant
  }),
  mcp.WithBaseURL("http://localhost:8080"),
)

mux := http.NewServeMux()
mux.Handle("/api/{tenant}/sse", sseServer.SSEHandler())
mux.Handle("/api/{tenant}/message", sseServer.MessageHandler())
```

* refactor(server): standardize URL path handling with normalizeURLPath

Replace manual path manipulation with a dedicated normalizeURLPath function
that properly handles path joining while ensuring consistent formatting.
The function:

- Always starts paths with a leading slash
- Never ends paths with a trailing slash (except for root path "/")
- Uses path.Join internally for proper path normalization
- Handles edge cases like empty segments, double slashes, and parent references

This eliminates duplicated code and creates a more consistent approach to
URL path handling throughout the SSE server implementation. Comprehensive
tests were added to validate the function's behavior.

Author: rwjblue-glean

examples/dynamic_path/main.go

@@ -0,0 +1,46 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+func main() {
+	var addr string
+	flag.StringVar(&addr, "addr", ":8080", "address to listen on")
+	flag.Parse()
+
+	mcpServer := server.NewMCPServer("dynamic-path-example", "1.0.0")
+
+	// Add a trivial tool for demonstration
+	mcpServer.AddTool(mcp.NewTool("echo"), func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+		return mcp.NewToolResultText(fmt.Sprintf("Echo: %v", req.Params.Arguments["message"])), nil
+	})
+
+	// Use a dynamic base path based on a path parameter (Go 1.22+)
+	sseServer := server.NewSSEServer(
+		mcpServer,
+		server.WithDynamicBasePath(func(r *http.Request, sessionID string) string {
+			tenant := r.PathValue("tenant")
+			return "/api/" + tenant
+		}),
+		server.WithBaseURL(fmt.Sprintf("http://localhost%s", addr)),
+		server.WithUseFullURLForMessageEndpoint(true),
+	)
+
+	mux := http.NewServeMux()
+	mux.Handle("/api/{tenant}/sse", sseServer.SSEHandler())
+	mux.Handle("/api/{tenant}/message", sseServer.MessageHandler())
+
+	log.Printf("Dynamic SSE server listening on %s", addr)
+	if err := http.ListenAndServe(addr, mux); err != nil {
+		log.Fatalf("Server error: %v", err)
+	}
+}
+

server/errors.go

@@ -2,6 +2,7 @@ package server
 
 import (
 	"errors"
+	"fmt"
 )
 
 var (
@@ -21,3 +22,12 @@ var (
 	ErrNotificationNotInitialized = errors.New("notification channel not initialized")
 	ErrNotificationChannelBlocked = errors.New("notification channel full or blocked")
 )
+
+// ErrDynamicPathConfig is returned when attempting to use static path methods with dynamic path configuration
+type ErrDynamicPathConfig struct {
+	Method string
+}
+
+func (e *ErrDynamicPathConfig) Error() string {
+	return fmt.Sprintf("%s cannot be used with WithDynamicBasePath. Use dynamic path logic in your router.", e.Method)
+}

server/sse.go

@@ -8,6 +8,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"net/url"
+	"path"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -34,6 +35,13 @@ type sseSession struct {
 // content. This can be used to inject context values from headers, for example.
 type SSEContextFunc func(ctx context.Context, r *http.Request) context.Context
 
+// 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
+
 func (s *sseSession) SessionID() string {
 	return s.sessionID
 }
@@ -58,19 +66,19 @@ type SSEServer struct {
 	server                       *MCPServer
 	baseURL                      string
 	basePath                     string
+	appendQueryToMessageEndpoint bool
 	useFullURLForMessageEndpoint bool
 	messageEndpoint              string
 	sseEndpoint                  string
 	sessions                     sync.Map
 	srv                          *http.Server
 	contextFunc                  SSEContextFunc
+	dynamicBasePathFunc          DynamicBasePathFunc
 
 	keepAlive         bool
 	keepAliveInterval time.Duration
 
 	mu sync.RWMutex
-
-	appendQueryToMessageEndpoint bool
 }
 
 // SSEOption defines a function type for configuring SSEServer
@@ -99,14 +107,25 @@ func WithBaseURL(baseURL string) SSEOption {
 	}
 }
 
-// WithBasePath adds a new option for setting base path
+// WithBasePath adds a new option for setting a static base path
 func WithBasePath(basePath string) SSEOption {
 	return func(s *SSEServer) {
-		// Ensure the path starts with / and doesn't end with /
-		if !strings.HasPrefix(basePath, "/") {
-			basePath = "/" + basePath
+		s.basePath = normalizeURLPath(basePath)
+	}
+}
+
+// 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 SSE server
+// creation, such as when using a reverse proxy or when the server is mounted
+// at a dynamic path.
+func WithDynamicBasePath(fn DynamicBasePathFunc) SSEOption {
+	return func(s *SSEServer) {
+		if fn != nil {
+			s.dynamicBasePathFunc = func(r *http.Request, sid string) string {
+				bp := fn(r, sid)
+				return normalizeURLPath(bp)
+			}
 		}
-		s.basePath = strings.TrimSuffix(basePath, "/")
 	}
 }
 
@@ -208,8 +227,8 @@ func (s *SSEServer) Start(addr string) error {
 
 	if s.srv == nil {
 		s.srv = &http.Server{
-			Addr:		addr,
-			Handler:	s,
+			Addr:    addr,
+			Handler: s,
 		}
 	} else {
 		if s.srv.Addr == "" {
@@ -218,7 +237,7 @@ func (s *SSEServer) Start(addr string) error {
 			return fmt.Errorf("conflicting listen address: WithHTTPServer(%q) vs Start(%q)", s.srv.Addr, addr)
 		}
 	}
-	
+
 	return s.srv.ListenAndServe()
 }
 
@@ -331,7 +350,7 @@ func (s *SSEServer) handleSSE(w http.ResponseWriter, r *http.Request) {
 	}
 
 	// Send the initial endpoint event
-	endpoint := s.GetMessageEndpointForClient(sessionID)
+	endpoint := s.GetMessageEndpointForClient(r, sessionID)
 	if s.appendQueryToMessageEndpoint && len(r.URL.RawQuery) > 0 {
 		endpoint += "&" + r.URL.RawQuery
 	}
@@ -355,13 +374,20 @@ func (s *SSEServer) handleSSE(w http.ResponseWriter, r *http.Request) {
 }
 
 // GetMessageEndpointForClient returns the appropriate message endpoint URL with session ID
-// based on the useFullURLForMessageEndpoint configuration.
-func (s *SSEServer) GetMessageEndpointForClient(sessionID string) string {
-	messageEndpoint := s.messageEndpoint
-	if s.useFullURLForMessageEndpoint {
-		messageEndpoint = s.CompleteMessageEndpoint()
+// for the given request. This is the canonical way to compute the message endpoint for a client.
+// It handles both dynamic and static path modes, and honors the WithUseFullURLForMessageEndpoint flag.
+func (s *SSEServer) GetMessageEndpointForClient(r *http.Request, sessionID string) string {
+	basePath := s.basePath
+	if s.dynamicBasePathFunc != nil {
+		basePath = s.dynamicBasePathFunc(r, sessionID)
+	}
+
+	endpointPath := normalizeURLPath(basePath, s.messageEndpoint)
+	if s.useFullURLForMessageEndpoint && s.baseURL != "" {
+		endpointPath = s.baseURL + endpointPath
 	}
-	return fmt.Sprintf("%s?sessionId=%s", messageEndpoint, sessionID)
+
+	return fmt.Sprintf("%s?sessionId=%s", endpointPath, sessionID)
 }
 
 // handleMessage processes incoming JSON-RPC messages from clients and sends responses
@@ -479,32 +505,111 @@ func (s *SSEServer) GetUrlPath(input string) (string, error) {
 	return parse.Path, nil
 }
 
-func (s *SSEServer) CompleteSseEndpoint() string {
-	return s.baseURL + s.basePath + s.sseEndpoint
+func (s *SSEServer) CompleteSseEndpoint() (string, error) {
+	if s.dynamicBasePathFunc != nil {
+		return "", &ErrDynamicPathConfig{Method: "CompleteSseEndpoint"}
+	}
+
+	path := normalizeURLPath(s.basePath, s.sseEndpoint)
+	return s.baseURL + path, nil
 }
 
 func (s *SSEServer) CompleteSsePath() string {
-	path, err := s.GetUrlPath(s.CompleteSseEndpoint())
+	path, err := s.CompleteSseEndpoint()
+	if err != nil {
+		return normalizeURLPath(s.basePath, s.sseEndpoint)
+	}
+	urlPath, err := s.GetUrlPath(path)
 	if err != nil {
-		return s.basePath + s.sseEndpoint
+		return normalizeURLPath(s.basePath, s.sseEndpoint)
 	}
-	return path
+	return urlPath
 }
 
-func (s *SSEServer) CompleteMessageEndpoint() string {
-	return s.baseURL + s.basePath + s.messageEndpoint
+func (s *SSEServer) CompleteMessageEndpoint() (string, error) {
+	if s.dynamicBasePathFunc != nil {
+		return "", &ErrDynamicPathConfig{Method: "CompleteMessageEndpoint"}
+	}
+	path := normalizeURLPath(s.basePath, s.messageEndpoint)
+	return s.baseURL + path, nil
 }
 
 func (s *SSEServer) CompleteMessagePath() string {
-	path, err := s.GetUrlPath(s.CompleteMessageEndpoint())
+	path, err := s.CompleteMessageEndpoint()
+	if err != nil {
+		return normalizeURLPath(s.basePath, s.messageEndpoint)
+	}
+	urlPath, err := s.GetUrlPath(path)
 	if err != nil {
-		return s.basePath + s.messageEndpoint
+		return normalizeURLPath(s.basePath, s.messageEndpoint)
 	}
-	return path
+	return urlPath
+}
+
+// SSEHandler returns an http.Handler for the SSE endpoint.
+//
+// This method allows you to mount the SSE handler at any arbitrary path
+// using your own router (e.g. net/http, gorilla/mux, chi, etc.). It is
+// intended for advanced scenarios where you want to control the routing or
+// support dynamic segments.
+//
+// IMPORTANT: When using this handler in advanced/dynamic mounting scenarios,
+// you must use the WithDynamicBasePath option to ensure the correct base path
+// is communicated to clients.
+//
+// Example usage:
+//
+//	// Advanced/dynamic:
+//	sseServer := NewSSEServer(mcpServer,
+//		WithDynamicBasePath(func(r *http.Request, sessionID string) string {
+//			tenant := r.PathValue("tenant")
+//			return "/mcp/" + tenant
+//		}),
+//		WithBaseURL("http://localhost:8080")
+//	)
+//	mux.Handle("/mcp/{tenant}/sse", sseServer.SSEHandler())
+//	mux.Handle("/mcp/{tenant}/message", sseServer.MessageHandler())
+//
+// For non-dynamic cases, use ServeHTTP method instead.
+func (s *SSEServer) SSEHandler() http.Handler {
+	return http.HandlerFunc(s.handleSSE)
+}
+
+// MessageHandler returns an http.Handler for the message endpoint.
+//
+// This method allows you to mount the message handler at any arbitrary path
+// using your own router (e.g. net/http, gorilla/mux, chi, etc.). It is
+// intended for advanced scenarios where you want to control the routing or
+// support dynamic segments.
+//
+// IMPORTANT: When using this handler in advanced/dynamic mounting scenarios,
+// you must use the WithDynamicBasePath option to ensure the correct base path
+// is communicated to clients.
+//
+// Example usage:
+//
+//	// Advanced/dynamic:
+//	sseServer := NewSSEServer(mcpServer,
+//		WithDynamicBasePath(func(r *http.Request, sessionID string) string {
+//			tenant := r.PathValue("tenant")
+//			return "/mcp/" + tenant
+//		}),
+//		WithBaseURL("http://localhost:8080")
+//	)
+//	mux.Handle("/mcp/{tenant}/sse", sseServer.SSEHandler())
+//	mux.Handle("/mcp/{tenant}/message", sseServer.MessageHandler())
+//
+// For non-dynamic cases, use ServeHTTP method instead.
+func (s *SSEServer) MessageHandler() http.Handler {
+	return http.HandlerFunc(s.handleMessage)
 }
 
 // ServeHTTP implements the http.Handler interface.
 func (s *SSEServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if s.dynamicBasePathFunc != nil {
+		http.Error(w, (&ErrDynamicPathConfig{Method: "ServeHTTP"}).Error(), http.StatusInternalServerError)
+		return
+	}
 	path := r.URL.Path
 	// Use exact path matching rather than Contains
 	ssePath := s.CompleteSsePath()
@@ -520,3 +625,21 @@ func (s *SSEServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 
 	http.NotFound(w, r)
 }
+
+// normalizeURLPath joins path elements like path.Join but ensures the
+// result always starts with a leading slash and never ends with a slash
+func normalizeURLPath(elem ...string) string {
+	joined := path.Join(elem...)
+
+	// Ensure leading slash
+	if !strings.HasPrefix(joined, "/") {
+		joined = "/" + joined
+	}
+
+	// Remove trailing slash if not just "/"
+	if len(joined) > 1 && strings.HasSuffix(joined, "/") {
+		joined = joined[:len(joined)-1]
+	}
+
+	return joined
+}