Proposal: Move GetSessionID closure into ServerOptions

[fgrosse]

Is your feature request related to a problem? Please describe.

I'm writing an MCP server using the StreamableHTTPHandler and need more control over generating session IDs. I'm aware of the StreamableHTTPOptions.GetSessionID() string setting, but the problem with this closure is that it needs to be assigned at the wrong time in the lifecycle of the server.

In my use case, I'm creating a custom mcp.Server for each new session (using the getServer(...) function argument of NewStreamableHTTPHandler(...)). This enables me to expose different MCP tools to different sessions. Now I also want to be able to use a custom per-server logic for assigning session IDs. For instance, I would like to copy the session ID from a downstream service. Currently, this is not possible because the StreamableHTTPOptions.GetSessionID() closure is assigned to the HTTP handler only once at application startup, rather than being an option of the mcp.Server, which can be created per-session.

Describe the solution you'd like

Moving the GetSessionID() closure out of the StreamableHTTPOptions into the ServerOptions would enable me to assign a function that can use per-session information instead of a closure that would only have information available at startup.

Details: Git diff

diff --git a/mcp/server.go b/mcp/server.go
index 69808ac..1621e4b 100644
--- a/mcp/server.go
+++ b/mcp/server.go
@@ -83,6 +83,16 @@ type ServerOptions struct {
 	// If true, advertises the tools capability during initialization,
 	// even if no tools have been registered.
 	HasTools bool
+
+	// GetSessionID provides the next session ID to use for an incoming request.
+	// If nil, a default randomly generated ID will be used.
+	//
+	// Session IDs should be globally unique across the scope of the server,
+	// which may span multiple processes in the case of distributed servers.
+	//
+	// As a special case, if GetSessionID returns the empty string, the
+	// Mcp-Session-Id header will not be set.
+	GetSessionID func() string
 }
 
 // NewServer creates a new MCP server. The resulting server has no features:
@@ -114,6 +124,11 @@ func NewServer(impl *Implementation, options *ServerOptions) *Server {
 	if opts.UnsubscribeHandler != nil && opts.SubscribeHandler == nil {
 		panic("UnsubscribeHandler requires SubscribeHandler")
 	}
+
+	if opts.GetSessionID == nil {
+		opts.GetSessionID = randText
+	}
+
 	return &Server{
 		impl:                    impl,
 		opts:                    opts,
diff --git a/mcp/streamable.go b/mcp/streamable.go
index 8ac6f59..f359b7c 100644
--- a/mcp/streamable.go
+++ b/mcp/streamable.go
@@ -50,16 +50,6 @@ type StreamableHTTPHandler struct {
 
 // StreamableHTTPOptions configures the StreamableHTTPHandler.
 type StreamableHTTPOptions struct {
-	// GetSessionID provides the next session ID to use for an incoming request.
-	// If nil, a default randomly generated ID will be used.
-	//
-	// Session IDs should be globally unique across the scope of the server,
-	// which may span multiple processes in the case of distributed servers.
-	//
-	// As a special case, if GetSessionID returns the empty string, the
-	// Mcp-Session-Id header will not be set.
-	GetSessionID func() string
-
 	// Stateless controls whether the session is 'stateless'.
 	//
 	// A stateless server does not validate the Mcp-Session-Id header, and uses a
@@ -92,9 +82,6 @@ func NewStreamableHTTPHandler(getServer func(*http.Request) *Server, opts *Strea
 	if opts != nil {
 		h.opts = *opts
 	}
-	if h.opts.GetSessionID == nil {
-		h.opts.GetSessionID = randText
-	}
 	return h
 }
 
@@ -233,7 +220,7 @@ func (h *StreamableHTTPHandler) ServeHTTP(w http.ResponseWriter, req *http.Reque
 		if sessionID == "" {
 			// In stateless mode, sessionID may be nonempty even if there's no
 			// existing transport.
-			sessionID = h.opts.GetSessionID()
+			sessionID = server.opts.GetSessionID()
 		}
 		transport = &StreamableServerTransport{
 			SessionID:    sessionID,

Describe alternatives you've considered

I've considered using the StreamableHTTPOptions.GetSessionID() closure, but it would not allow me to take any per-session information into account because it's assigned once at startup.

Another alternative could be to add more parameters to the StreamableHTTPOptions.GetSessionID() function (e.g., the request context). That would work for me, but it would also encourage people to smuggle values with the request context, which I consider to be an antipattern.

Additional context

none

[fgrosse]

I'm happy to provide a PR, including unit tests, and if wanted, a backwards compatible implementation (I know the v1 release is supposed to happen soon).

Backward compatibility could be implemented by keeping the StreamableHTTPOptions.GetSessionID field and just adding the new ServerOptions.GetSessionID field. If the latter is not nil, it can take precedence. Of course, this would add complexity so there is value in avoiding that (pre v1).

[findleyr]

Funny, I was actually wondering on my bike ride in to work whether we should have added the http.Request to GetSessionID. It certainly changes the meaning of that callback.

I think we'd have to do this in a backward-compatible way, deprecating the current callback if necessary. That's OK if we can agree on this proposal.

There is a lot of discussion happening about what a session even is.
For example: modelcontextprotocol/modelcontextprotocol#1364
I'd like to defer committing to too much API before that discussion resolves.

Can you explain why the ServerSession.ID accessor is not sufficient for your use case? Especially since you indicated that you don't want to encode information into the session ID (which I think I agree with in principle), couldn't you track session-specific information by its ID?

[fgrosse]

whether we should have added the http.Request to GetSessionID

That would work in my case, but it would force me to smuggle values via the HTTP Request.Context().

Can you explain why the ServerSession.ID accessor is not sufficient for your use case?

What I want to do is to take full control over calculating the session ID - essentially letting the server use a specific session ID string from a downstream system instead of calculating a new one. I didn't find ServerSession.ID (maybe that's on a release branch I don't have access to?) However, it looks like this would just allow me to read the session ID value, not change how it's assigned.

you indicated that you don't want to encode information into the session ID

I agree that session IDs should just be opaque strings. However, to calculate them, I want to have the context of the HTTP request or at least the context of the MCP server. My use case specifically is about using another opaque ID as MCP session ID which I cannot know at application startup. Instead the ID I want my server to assign is only known per session creation.

[jba]

I think we'd have to do this in a backward-compatible way, deprecating the current callback if necessary. That's OK if we can agree on this proposal.

Sorry for the confusion: it was this issue that I meant to mark as a release blocker, for this reason. If we think it's the right solution and is strictly more general, we can do it today.

[findleyr]

Originally we tried to keep SessionID scoped to the transport layer. However, it seems inevitable that it gets absorbed by the protocol layer, and in any case it's not a bad thing for every session to have an ID.

And in fact, we expose ServerSession.ID. We had to do some hacky stuff to implement this: originally, SessionID was on the Connection, and that just really didn't feel right. Now we smuggle it through the Streamable connection using an unexported method.

Moving it to ServerOptions makes a lot of sense, to make the SessionID an intrinsic attribute of the session, and is strictly more powerful than GetSessionID(*http.Request). It also makes GetSessionID less overlapping conceptually than Stateless.

We'd have to allow passing in a session id when constructing the session. likely on ServerSessionOptions.

So, I actually think we should do this. The question is: is it too late to remove StreamableHTTPOptions.GetSessionID? If we're concerned about the breakage, we can safely deprecate it and say that if set it takes precedent over the session ID provided by the server.

[fgrosse]

I would argue that this should either be a release blocker for the v1 release or be marked as a breaking change once a compatibility guarantee exists after v1 was merged.

That being said, I'm fine with either decision and will move ahead opening a PR so we have a place to more easily talk about the specifics of the code change.

Also thanks for all the input and quick turnaround here 👍

[jba]

We'd have to allow passing in a session id when constructing the session. likely on ServerSessionOptions.

Can you explain where this comes into play? Server.Connect can use Server.opts.GetSessionID. Although I guess that results in a second call in streamable.go:312?

[findleyr]

Can you explain where this comes into play?

In stateless mode, we discard the session and recreate it on subsequent requests. So we'd need to be able to reassign the same session ID.

[jba]

Can you explain where this comes into play?

In stateless mode, we discard the session and recreate it on subsequent requests. So we'd need to be able to reassign the same session ID.

Does that require public API?

[findleyr]

Does that require public API?

Not immediately, no.

[fgrosse]

I would argue that this should either be a release blocker for the v1 release or be marked as a breaking change once a compatibility guarantee exists after v1 was merged.

I have opened a PR without the backwards compatibility now. Let me know if you would prefer another approach, e.g., keeping but deprecating the old closure.