HttpServlet Streamable HTTP server implementation #290

ZachGerman · 2025-06-02T20:49:39Z

Not planned:

Backward-compatible endpoint combo

Motivation and Context

This has been created by collaboration between @ZachGerman, @chemicL, & @tzolov to bring the much desired feature of Streamable HTTP transport to the Java SDK with three transport providers to choose from.

How Has This Been Tested?

Unit testing along with a suite of abstract integration tests.

Breaking Changes

N/A

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

...ain/java/io/modelcontextprotocol/server/transport/StreamableHttpServerTransportProvider.java

chemicL

Hey 👋 Thanks for a comprehensive PR! I did my first round focusing on the main themes. Happy to offer guidance to cover the essential aspects (simple/stateful servers, multiple streams per session, lifecycle) if you'd like to push this forward.

...ain/java/io/modelcontextprotocol/server/transport/StreamableHttpServerTransportProvider.java

ZachGerman · 2025-06-17T23:46:15Z

Thank you very much for all of the input @chemicL! I will begin making changes accordingly this afternoon.

ZachGerman · 2025-06-25T16:05:33Z

Today I'm targeting origin header validation and moving the dedicated GET stream to the StreamableHttpSession class, then adding an integ test for GET on /mcp to start the listening stream.
After that, I believe we should have all core functionality except sessionless and proper SSE response upgrade logic.

sivankri · 2025-06-26T02:56:45Z

Hi @ZachGerman I tried using your StreamableHttpServerTransportProvider.java file + java MCP SDK 0.10.0. My backend server is Jetty 12. The request from MCP Interceptor hangs in the below call.

return streamSession.handle(message).then(Mono.just(responseType)).onErrorReturn(ResponseType.IMMEDIATE);

This is the actuall line which gets blocked
--McpServerSession.java --> return var10000.flatMap(var10001::sendMessage);

Can you please check this?

tzolov · 2025-06-26T10:20:13Z

Today I'm targeting origin header validation and moving the dedicated GET stream to the StreamableHttpSession class, then adding an integ test for GET on /mcp to start the listening stream. After that, I believe we should have all core functionality except sessionless and proper SSE response upgrade logic.

@ZachGerman what do you mean by origin header validation? I hope it is not overlapping with the #284

chemicL

Added a few more comments.

chemicL · 2025-06-26T12:25:36Z

...ain/java/io/modelcontextprotocol/server/transport/StreamableHttpServerTransportProvider.java

+		if (sessionId == null) {
+			response.setContentType(APPLICATION_JSON);
+			response.setStatus(HttpServletResponse.SC_BAD_REQUEST);
+			response.getWriter().write(createErrorJson("Session ID missing in request header"));


modelcontextprotocol/modelcontextprotocol#282 please check this issue. I'm leaning towards separating the JSON-RPC lifecycle from the lower level transport lifecycle. In that world, GET and POST and session concepts are not at the JSON-RPC layer, so the lifecycle does not apply. In fact, the previous SSE transport did begin with a HTTP GET request before the initialization request could have been sent. For the stateless servers it should definitely be improved in the spec to mention that initialization is not required before other requests.

[EDIT]

For the record, the above was wishful thinking. I agree we are only able to generate the session ID upon POST of the initialize request. The spec is in fact melding the json-rpc layer with http, so the session ID gets generated only when processing a initialization request:

A server using the Streamable HTTP transport MAY assign a session ID at initialization time, by including it in an Mcp-Session-Id header on the HTTP response containing the InitializeResult

chemicL · 2025-06-26T14:06:23Z

...ain/java/io/modelcontextprotocol/server/transport/StreamableHttpServerTransportProvider.java

+		// Subscribe to the SSE stream and write events to the response
+		sseStream.getEventFlux().doOnNext(event -> {
+			try {
+				if (event.id() != null) {


Right, but do we emit events with no ID ? Reading the code I don't see a situation like this. My understanding of the mentioned spec is that if the ID is missing then the client would not use this id for Last-Event-ID tracking, but we are on the server side and we always generate an ID.

...ain/java/io/modelcontextprotocol/server/transport/StreamableHttpServerTransportProvider.java

ZachGerman · 2025-06-26T18:57:56Z

@sivankri: Changing the related logic after my meeting with Dariusz this morning, so (hopefully) your issue goes away with the new response type mapping.
@tzolov: It's related, but I don't think it's overlapping as I'm just adding the ability to set a list of allowed origins to the server transport provider and enforcing it if it's set.

viyaviya · 2025-06-27T08:40:03Z

merge commit 6c4830b is bad

ZachGerman · 2025-06-27T15:33:59Z

merge commit 6c4830b is bad

Oops! Thanks for the heads up! Fixed!

ZachGerman · 2025-06-27T18:07:35Z

@sivankri the new logic added streamTools to McpServerFeatures, used in the Async constructor, which facilitates a list of tool specifications that return Flux instead of Mono via the new AsyncStreamingToolSpecification record type and uses the return type of the call to differentiate between direct-HTTP and SSE-stream responses.

...ain/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java

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

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

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

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

sivankri · 2025-07-01T15:59:02Z

@ZachGerman I tried running my mcp remote server against the mcp sdk generated from your branch. When i used the MCP inspector tool by setting query parameter transport=streamable-http, i could not get the connection established. Can you please help me with this?

ZachGerman · 2025-07-01T18:29:23Z

@sivankri I'm unfamiliar with the MCP inspector tool, but I imagine it's related to the fact that this JDK has public static final String LATEST_PROTOCOL_VERSION = "2024-11-05"; in the McpSchema spec class & that is currently used for all server instantiation. You can update it locally and the server from my branch, as well as @chemicL's webClient, should work with the update, but it will break a lot of tests. I plan on tackling protocol version negotiation soon if nobody else does.

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

ZachGerman · 2025-07-08T06:48:52Z

Once I realized that I needed to identify the transports in the exchange's session from the tool handlers, I realized I need to either pass the entire JSONRPCRequest to the handler (instead of the request.params()), or add a third request.id() parameter to tool handlers.

Either way, it brought more attention to the fact that we were using Object for JSONRPCRequest/Response id, so I added a little sub-class in the McpSchema to enforce the "(String | Number) && Non-null" requirements of that field.

Tomorrow I will be making the JSONRPCRequest id available to tool handlers and it can be passed to the McpAsyncServerExchange class methods in order to route notifications and requests to the related SSE stream.

Edit: Ended up going with a per-request exchange instance instead of passing transport ID to tool call handlers. This allows tool implementers to not worry about transport routing with their exchange method calls.

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

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

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

Signed-off-by: Christian Tzolov <[email protected]>

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

…protocol#425) - Add WebMvcStreamableServerTransportProvider with SSE support for streamable sessions - Support GET, POST, DELETE endpoints for MCP protocol operations - Implement thread-safe SSE operations using ReentrantLock in WebMvcSseServerTransportProvider - Add test infrastructure with AbstractMcpClientServerIntegrationTests - Refactor WebMvcStreamableIntegrationTests to use parameterized tests - Support testing with both HttpClient and WebFlux transports - Add streamable transport tests for both async and sync server modes - Refactor existing WebMVC SSE integration tests to use shared test base - Add error handling improvements in McpStreamableServerSession - Update dependencies: add json-unit-assertj for enhanced JSON testing - Reorganize POM dependencies and add mcp-spring-webflux test dependency This change enables Spring WebMVC applications to use the streamable MCP transport protocol with proper thread safety guarantees and comprehensive test coverage. Related to modelcontextprotocol#72 Signed-off-by: Christian Tzolov <[email protected]>

- Wrap consumer, tool, resource, prompt, and completion handler calls with Mono.defer() - Ensures proper lazy evaluation and error handling in reactive streams Signed-off-by: Christian Tzolov <[email protected]>

- Add HttpServletStreamableServerTransportProvider for MCP streamable transport - Provides HttpServlet equivalent of WebMvcStreamableServerTransportProvider without Spring dependencies - Support for GET (SSE connections/replay), POST (JSON-RPC messages), and DELETE (session cleanup) operations - Include comprehensive integration test suite with sampling, elicitation, roots, and tools testing - Add async/sync server test implementations for HttpServlet transport Signed-off-by: Christian Tzolov <[email protected]>

Signed-off-by: Christian Tzolov <[email protected]>

qcloop · 2025-07-30T18:23:15Z

Thanks for great work. Is there a coordination with Spring AI MCP? Would love to take it for a test drive

ZachGerman commented Jun 2, 2025

View reviewed changes

...ain/java/io/modelcontextprotocol/server/transport/StreamableHttpServerTransportProvider.java Outdated Show resolved Hide resolved

ZachGerman commented Jun 2, 2025

View reviewed changes

...ain/java/io/modelcontextprotocol/server/transport/StreamableHttpServerTransportProvider.java Outdated Show resolved Hide resolved

ZachGerman mentioned this pull request Jun 4, 2025

Support "Streamable HTTP" transport #72

Closed

8 tasks

oliveregger mentioned this pull request Jun 16, 2025

MCP Server integration ahdis/matchbox#398

Open

chemicL requested changes Jun 17, 2025

View reviewed changes

chemicL reviewed Jun 17, 2025

View reviewed changes

...ain/java/io/modelcontextprotocol/server/transport/StreamableHttpServerTransportProvider.java Outdated Show resolved Hide resolved

chemicL reviewed Jun 17, 2025

View reviewed changes

...ain/java/io/modelcontextprotocol/server/transport/StreamableHttpServerTransportProvider.java Outdated Show resolved Hide resolved

chemicL reviewed Jun 26, 2025

View reviewed changes

ZachGerman force-pushed the StreamableHttpServerTransportProvider branch from 6c4830b to 7817da6 Compare June 27, 2025 16:45

ZachGerman commented Jun 30, 2025

View reviewed changes

...ain/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java Outdated Show resolved Hide resolved

ZachGerman commented Jun 30, 2025

View reviewed changes

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncStreamableHttpServer.java Outdated Show resolved Hide resolved

ZachGerman commented Jun 30, 2025

View reviewed changes

mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java Outdated Show resolved Hide resolved

sivankri reviewed Jul 1, 2025

View reviewed changes

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncStreamableHttpServer.java Outdated Show resolved Hide resolved

sivankri reviewed Jul 1, 2025

View reviewed changes

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java Outdated Show resolved Hide resolved

stantonk mentioned this pull request Jul 1, 2025

feat: implement HttpClient Streamable HTTP transport #337

Closed

ZachGerman changed the title ~~Adding StreamableHttpServerTransportProvider class and unit tests~~ Adding StreamableHttpServerTransportProvider class along with unit & integration tests Jul 1, 2025

sivankri reviewed Jul 2, 2025

View reviewed changes

mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java Outdated Show resolved Hide resolved

ZachGerman force-pushed the StreamableHttpServerTransportProvider branch 2 times, most recently from 244208d to 25ff3dc Compare July 8, 2025 06:40

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 added this to the 0.11.0 milestone Jul 25, 2025

chemicL and others added 7 commits July 25, 2025 17:22

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

92ca81f

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

WIP: Sync server builder tests

c0e3129

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

WIP: resolve integration test issues

a0ad5a5

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

WIP: Logging notifications tests on exchange adapted

d98b8c9

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

WIP: Get rid of initialization notification handler

6e66602

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

refactor: improve MCP server test architecture with parameterized tests

b382ac5

Signed-off-by: Christian Tzolov <[email protected]>

WIP: stateless server implementation

0a4ecb0

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

ZachGerman force-pushed the StreamableHttpServerTransportProvider branch from 29a39f7 to c23c5df Compare July 29, 2025 20:17

ZachGerman changed the title ~~Adding StreamableHttpServerTransportProvider class along with unit & integration tests~~ Streamable HTTP Server abstractions and HttpServlet, WebFlux, & WebMVC transport providers Jul 30, 2025

chemicL and others added 11 commits July 30, 2025 11:03

WIP: context extractor usage, some javadocs, HttpHeaders constants

87a018f

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

WIP: Add remaining javadocs, tiny corrections here and there

92be635

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

Add accept header check for WebFlux server

08900bc

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

Use random port in McpCompletionTests

ca7f870

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

Merge branch 'main' into streamable-server-webmvc

f4eb55b

refactor: wrap handler invocations with Mono.defer for lazy evaluation

8a2e978

- Wrap consumer, tool, resource, prompt, and completion handler calls with Mono.defer() - Ensures proper lazy evaluation and error handling in reactive streams Signed-off-by: Christian Tzolov <[email protected]>

Added 'Accept' header validation and touched up 'Last-Event-ID' header

dcd6903

Merge branch 'main' into StreamableHttpServerTransportProvider

83f931c

conflict resolution

b4b33d6

Signed-off-by: Christian Tzolov <[email protected]>

tzolov force-pushed the StreamableHttpServerTransportProvider branch from 5c09fa5 to b4b33d6 Compare July 30, 2025 14:43

tzolov changed the title ~~Streamable HTTP Server abstractions and HttpServlet, WebFlux, & WebMVC transport providers~~ HttpServlet Streamable HTTP server implementation Jul 30, 2025

align headers

66ce6c4

chemicL approved these changes Jul 30, 2025

View reviewed changes

chemicL merged commit bde1b6b into modelcontextprotocol:main Jul 30, 2025
1 of 2 checks passed

HttpServlet Streamable HTTP server implementation #290

HttpServlet Streamable HTTP server implementation #290

Conversation

ZachGerman commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

Uh oh!

Uh oh!

chemicL left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ZachGerman commented Jun 17, 2025

Uh oh!

ZachGerman commented Jun 25, 2025

Uh oh!

sivankri commented Jun 26, 2025

Uh oh!

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

Uh oh!

Uh oh!

chemicL left a comment

Choose a reason for hiding this comment

Uh oh!

chemicL Jun 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!

chemicL Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

viyaviya commented Jun 27, 2025

Uh oh!

ZachGerman commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZachGerman commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sivankri commented Jul 1, 2025

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

qcloop commented Jul 30, 2025

Uh oh!

Uh oh!

ZachGerman commented Jun 2, 2025 •

edited

Loading

tzolov commented Jun 26, 2025 •

edited

Loading

chemicL Jun 26, 2025 •

edited

Loading

ZachGerman commented Jun 26, 2025 •

edited

Loading

ZachGerman commented Jun 27, 2025 •

edited

Loading

ZachGerman commented Jun 27, 2025 •

edited

Loading

ZachGerman commented Jul 1, 2025 •

edited

Loading

ZachGerman commented Jul 8, 2025 •

edited

Loading