McpServerSession lifecycle doesn't support distributed services

[marianogonzalez]

This issue is closely related to #273 and could be considered as a follow up to that, but I decided to split it for convenience and readability.

Consider an MCP server written with this SDK and using the StreamableHttp transport. We deploy two replicas (A and B) of this server, with a load balancer in front.

1. A new client application initiates a session by sending an initialize message, followed by a notifications/initialized notifications.
2. Let's say that the Load Balancer routed both messages to replica A
3. As a result, replica A generated a new session which Id is communicated back to the client
4. Replica A now has an McpServerSession instance properly initialized with all the necessary client information

Problem:

1. Next the client sends a tools/list message with the obtain sessionId, but this time the load balancer routes the message to replica B
2. Even though I believe it should be the server's responsibility to share the session id across replicas, the McpServerSession instance that lives in replica B has never received (and will never receive) the initialize message and notifications
3. Although it's possible to distribute all that state and simulate that handshake in replica B (I actually did it), I think this SDK should have an OOTB support for that, or at the very least, SessionFactory methods that make it easier to generate "ready to use" Sessions based on previous initializations.

[alexanderqiu]

add one

[iaculch]

spring-session support would be nice here, we currently use the JDBC spring session store type and I would expect SSE sessions to ideally use the same / similar mechanism

[gianielsevier]

The current McpAsyncServer constructor unconditionally sets a default sessionFactory on the provided McpTransportProvider, even if a custom factory has already been injected. This makes it impossible to plug in a distributed session store such as Hazelcast, Redis, etc... for cross-pod session sharing in a multi-instance deployment.

In my case, I registered a Hazelcast-backed sessionFactory on the McpTransportProvider prior to constructing the server, but it was silently overwritten. This behavior breaks the ability to externalize session state, which is critical for stateless MCP server deployments behind a load balancer.

Suggested improvement: Before setting the default factory, the constructor could check whether McpTransportProvider already has a sessionFactory defined. If so, it should respect the existing one or allow injection via the builder. This would enable advanced use cases like distributed caching, session affinity, and custom lifecycle management without requiring deep overrides or manual patching.

[sargue]

I'm using this SDK to add MCP support to a Java app that's deployed in a cluster. The app is completely stateless, and I just realized this Java SDK for MCP server is not.

I've seen already several issues related more or less to this issue. This is one of those.

For now I think I will implement stickiness for the /mcp endpoint. But I'm not sure that completely solves the issue. For example, what about the io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider#notifyClients method?

I'm just starting with this SDK but this seems worth an improved documentation on the official docs site.

[mikegron]

You can use the new Stateless server which does not include sessions, assuming you don't need any.

[sargue]

I wasn't aware that was a thing!

No mention on the docs: https://modelcontextprotocol.io/sdk/java/mcp-server

Before going through the SDK code, what's the downside of going with the stateless server? Because I guess there's some, otherwise, we bother with state if we don't need it for something?

[quaff]

what's the downside of going with the stateless server? Because I guess there's some, otherwise, we bother with state if we don't need it for something?

Quoted from https://docs.spring.io/spring-ai/reference/1.1-SNAPSHOT/api/mcp/mcp-stateless-server-boot-starter-docs.html

The stateless servers don’t support message requests to the MCP client (e.g., elicitation, sampling, ping).

[yitzhaktal]

Add one

[Lightroy]

Add one

[stantonk]

FWIW, the Stateless transport works well if all you're doing is providing MCP Tools and thus instantly makes tool services horizontally scalable. Stateless is a part of the MCP spec and is supported by clients that support StreamableHTTP. E.g. Langhchain4j's MCP client works fine with the Stateless implementation in the java-sdk.

That said, agreed that there will be cases where people want stateful MCP for some of the other capabilities it provides, and being able to plug one's own implementation in for session management/storage is a nice way to make stateful MCP horizontally scalable.