[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 <[email protected]>

…raction Signed-off-by: Dariusz Jędrzejczyk <[email protected]>

Signed-off-by: Dariusz Jędrzejczyk <[email protected]>

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

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?

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?

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?

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.

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

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.

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?

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.

…sync server tests Signed-off-by: Dariusz Jędrzejczyk <[email protected]>

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

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?

chemicL added 5 commits July 18, 2025 12:01

WIP

98990e9

Signed-off-by: Dariusz Jędrzejczyk <[email protected]>

Merge branch 'main' into streamable-server

8e4c745

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

f83db45

…raction Signed-off-by: Dariusz Jędrzejczyk <[email protected]>

Formatting

1645ecb

Signed-off-by: Dariusz Jędrzejczyk <[email protected]>

WIP: make it compile

a3ddb75

Signed-off-by: Dariusz Jędrzejczyk <[email protected]>

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 <[email protected]>

WIP: make it compile

6423fcd

Signed-off-by: Dariusz Jędrzejczyk <[email protected]>

WIP: add SSE id generation and DELETE handling

8e9ab52

Signed-off-by: Dariusz Jędrzejczyk <[email protected]>

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 <[email protected]>

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

[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!

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!

Uh oh!

tzolov Jul 26, 2025 •

edited

Loading