[WIP] Streamable HTTP Server abstractions and WebFlux transport provider #420

chemicL · 2025-07-22T14:46:17Z

Still WIP, but this outlines the direction for the Streamable HTTP server side. It is based on the research started with cooperation with @ZachGerman in #290. Eventually, Zach's PR should be able to be rebased on top of this work and we will have two transport implementations (WebFlux and JDK Servlet-based).

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

…raction Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

He-Pin · 2025-07-23T17:08:34Z

can we support sse and streamble at the same time ？

ZachGerman · 2025-07-24T20:21:34Z

can we support sse and streamble at the same time ？

We could with spec support for something like this, amongst other routes.

gemo12123 · 2025-07-25T01:08:07Z

Will WebMVC based implementations be provided in the future? My project is based on WebMVC and has been running for some time now. I don't want to modify it to WebFlux anymore.

weicheng113 · 2025-07-25T01:26:02Z

I agree with @gemo12123 . Plain Java without reactive version should be supported, especially with Project Loom.

tzolov

Here are some initial findings, while going through the code

tzolov · 2025-07-24T17:48:51Z

mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java

@@ -70,8 +73,9 @@ public class McpServerSession implements McpSession {
 	 * @param notificationHandlers map of notification handlers to use
 	 */
 	public McpServerSession(String id, Duration requestTimeout, McpServerTransport transport,
-			InitRequestHandler initHandler, InitNotificationHandler initNotificationHandler,
-			Map<String, RequestHandler<?>> requestHandlers, Map<String, NotificationHandler> notificationHandlers) {
+			McpInitRequestHandler initHandler, InitNotificationHandler initNotificationHandler,


InitNotificationHandler -> McpInitNotificationHandler

Actually, this notification handler can go away. I intend to deprecate this constructor in favor of a one that doesn't have it. We actually provide an empty handler in McpAsyncServer, so this is useless.

tzolov · 2025-07-24T18:12:17Z

mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java

@@ -9,6 +9,9 @@

 import com.fasterxml.jackson.core.type.TypeReference;
 import io.modelcontextprotocol.server.McpAsyncServerExchange;
+import io.modelcontextprotocol.server.McpInitRequestHandler;


I believe the McpInitRequestHandler, McpNotificationHandler, McpRequestHandler should be under the spec package?

They are server-specific and work either with the exchange or with the InitializeRequest, which itself is handled by the server side.

tzolov · 2025-07-24T18:17:41Z

mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java

+	/**
+	 * Request handler for the initialization request.
+	 */
+	public interface InitRequestHandler {


Don't think this is used and should be removed?

It is used. McpAsyncServer creates one and feeds it into DefaultMcpStreamableServerSessionFactory that gets passed onto the McpStreamableServerTransportProvider.

tzolov · 2025-07-24T18:17:51Z

mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java

+	/**
+	 * Notification handler for the initialization notification from the client.
+	 */
+	public interface InitNotificationHandler {


Don't think this is used and should be removed?

Correct, removed.

tzolov · 2025-07-25T07:38:10Z

mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java

+	}
+
+	@FunctionalInterface
+	interface RequestHandler<T> extends BiFunction<McpTransportContext, Object, Mono<T>> {


This should be called StatlessRequestHandler.

Also all request and notification handlers should be grouped in common (parent) package inside the spec.

tzolov · 2025-07-25T07:39:38Z

mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java

+		this.uriTemplateManagerFactory = uriTemplateManagerFactory;
+		this.jsonSchemaValidator = jsonSchemaValidator;
+
+		Map<String, RequestHandler<?>> requestHandlers = new HashMap<>();


I believe we will need notification handling as well. I guess we will need stateless notification handler as well.

I'll try to come up with a shared abstraction to contain these handlers under an composite class.

tzolov · 2025-07-25T09:31:11Z

mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java

+		});
+	}
+
+	public Mono<Void> accept(McpSchema.JSONRPCNotification notification) {


The accept(McpSchema.JSONRPCNotification notification) and accept(McpSchema.JSONRPCResponse response) methods appear to be a split version of McpServerSession#handle(McpSchema.JSONRPCMessage message). For consistency, I’d prefer we stick with a single handler method.

Additionally, I believe a handle(Message) abstraction should be part of the McpSession interface. Since McpSession represents bidirectional JSON-RPC communication—already exposing sendXyz(Message) for outgoing messages—it makes sense to also include a handle(Message) method for incoming communication.

In fact all McpSession implement some form of handle(Msg). This applies for the clients as well

The accept(McpSchema.JSONRPCNotification notification) and accept(McpSchema.JSONRPCResponse response) methods appear to be a split version of McpServerSession#handle(McpSchema.JSONRPCMessage message). For consistency, I’d prefer we stick with a single handler method.

Unfortunately, with handle(McpSchema.JSONRPCMessage message) you are communicating to the implementor that all of possible messages can be passed in. That is not my intention. I specifically want to convey that either a response or a notification is handled via this accept method. Handling requests requires providing a dedicated transport, hence it has a different signature.

Regarding the rest of the comment, my changes are intended to introduce minimal breakages. Without the per-request SSE streams the above would make sense potentially, but with the specific transport argument for request handling and lack of such for notifications and responses makes it a non-goal for this PR. I'm open to discussion, but I believe opening this pandora's box is exactly what I tried to avoid here. The reason is that with a generic handle you have to manage the specific transport routing inside the session, something that is not a concern of the session itself, but of the transport. This is something explored in #290 that I tried to make less error prone with concrete transport instances that are 1-1 mapped to a request.

tzolov · 2025-07-25T09:40:24Z

mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java

+			requestHandlers.put(McpSchema.METHOD_COMPLETION_COMPLETE, completionCompleteRequestHandler());
+		}
+
+		mcpTransport.setRequestHandler((context, request) -> requestHandlers.get(request.method())


It is a good point that we don't use McpSession as the stateless server is unidirectional and should support only the handle(Message) for request and notifications.

Related to my other comment about the McpSession not having handle(msg). Perhaps we can introduce McpHandlerSession that has handle(JSONRPCMessage) used by the stateless server). Then the McpSession can extend it.

I intend to add a composite for the notification and request handlers. But I'd suggest avoiding the abstraction of handle(JSONRPCMessage) as that conveys the notion that we can handle responses here - we should not, that is an error in the stateless server (at least in my view). Also, I suggest we avoid using "Session" as part of this composite's name to avoid even further confusion for stateless server authors - the intention for them is to handle "sessionless" situations, so a session (despite being a JSON-RPC layer concept from our early implementation) would be rather confusing.

tzolov · 2025-07-25T09:55:20Z

mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java

+public interface McpStatelessServerTransport {
+
+	void setRequestHandler(
+			BiFunction<McpTransportContext, McpSchema.JSONRPCRequest, Mono<McpSchema.JSONRPCResponse>> message);


The signature of the setRequestHandler needs to change from JSONRPCRequest to JSONRPCMessage to allow handling both requests and notifications?

As explained in the comments above, a composite will cover requests and notifications.

tzolov · 2025-07-25T10:58:16Z

mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java

+			Mono<McpSchema.InitializeResult> initResult) {
+	}
+
+	public final class McpStreamableServerSessionStream implements McpSession {


The McpStreamableServerSessionStream isn't bidirectional like McpSession.
We can split this into two interfaces:

McpRpcSender - handles outgoing messages (copies current McpSession functionality)

McpRpcReceiver - handles incoming messages with handle(JSONRPCMessage)
(names be refined)

McpSession would implement both interfaces, McpStreamableServerSessionStream would only implement McpRpcSender, and the Stateless Server would use McpRpcReceiver.

I think this comment is outdated after our 1-1 sync? McpStreamableServerSessionStream is bidirectional.

…sync server tests Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

tzolov · 2025-07-26T07:45:51Z

mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java

@@ -44,7 +44,7 @@ public final class McpSchema {
 	private McpSchema() {
 	}

-	public static final String LATEST_PROTOCOL_VERSION = "2024-11-05";
+	public static final String LATEST_PROTOCOL_VERSION = "2025-03-26";


The LATEST_PROTOCOL_VERSION unfortunately is used for all client and server transports and raising it to 2025-03-26 would likely cause misbehaviors.
One temporal solution is to let the transport implementations determine the protocol version. Something like this suggestion: #404
Then the init result should pick those version. Maybe the MpcTransport can have getSupporteProtocolVersion field or a like

This is not something I wanted to deal with in this PR but I guess we have to. I'm not sure how #404 addresses this? The protocol version handling in McpAsyncServer deals with the JSON-RPC MCP domain-level checks and that's what I think was failing when I stumbled upon the need to update this. I think we just have the "latest" concept so it is accurate. Please advise how we can go about this if you have more insight, I was unfortunately quite ignorant to this aspect :(

tzolov · 2025-07-26T08:13:14Z

.../java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java

+						McpSchema.JSONRPCResponse jsonrpcResponse = new McpSchema.JSONRPCResponse(
+								McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(), initializeResult, null);
+						try {
+							return this.objectMapper.writeValueAsString(jsonrpcResponse);


This seems redundant as the WebFlux would do the conversion?

I suppose so! Although it's a temporary mitigation, I think we should deal with the init result conversion into JSON at an earlier layer. Need to come back to this.

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

chemicL added 5 commits July 18, 2025 12:01

WIP

98990e9

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

Merge branch 'main' into streamable-server

8e4c745

More WIP: renaming, steteless server abstractions, client context ext…

f83db45

…raction Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

Formatting

1645ecb

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

WIP: make it compile

a3ddb75

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

chemicL added this to the 0.11.0 milestone Jul 22, 2025

chemicL mentioned this pull request Jul 3, 2025

Support "Streamable HTTP" transport #72

Open

7 tasks

tzolov mentioned this pull request Jul 22, 2025

Release 0.11.0 #386

Open

chemicL added 3 commits July 22, 2025 18:24

WIP: Add session ID to exchange

cef7aac

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

WIP: make it compile

6423fcd

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

WIP: add SSE id generation and DELETE handling

8e9ab52

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

tzolov reviewed Jul 25, 2025

View reviewed changes

WIP: Handle logging notifications, start with integration tests and a…

92ca81f

…sync server tests Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

tzolov reviewed Jul 26, 2025

View reviewed changes

tzolov mentioned this pull request Jul 26, 2025

[WIP] feat: Add Spring WebMVC streamable server transport provider #425

Draft

9 tasks

chemicL and others added 6 commits July 28, 2025 13:18

WIP: Sync server builder tests

c0e3129

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

WIP: resolve integration test issues

a0ad5a5

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

WIP: Logging notifications tests on exchange adapted

d98b8c9

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

WIP: Get rid of initialization notification handler

6e66602

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

refactor: improve MCP server test architecture with parameterized tests

b382ac5

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

WIP: stateless server implementation

0a4ecb0

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

[WIP] Streamable HTTP Server abstractions and WebFlux transport provider #420

Are you sure you want to change the base?

[WIP] Streamable HTTP Server abstractions and WebFlux transport provider #420

Conversation

chemicL commented Jul 22, 2025

Uh oh!

He-Pin commented Jul 23, 2025

Uh oh!

ZachGerman commented Jul 24, 2025

Uh oh!

gemo12123 commented Jul 25, 2025

Uh oh!

weicheng113 commented Jul 25, 2025

Uh oh!

tzolov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chemicL Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tzolov Jul 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chemicL Jul 28, 2025 •

edited

Loading

tzolov Jul 26, 2025 •

edited

Loading