Streamable HTTP Server abstractions and HttpServlet, WebFlux, & WebMVC transport providers #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]>

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

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]>

- Add WebMvcStreamableServerTransportProvider for non-reactive MCP server support - Implement HTTP/SSE transport with session management and graceful shutdown - Support GET, POST, DELETE endpoints for MCP protocol operations - Add test suite including integration tests with Tomcat - Refactor AbstractMcpAsyncServerTests to support multiple transport implementations - Provide WebMVC alternative to existing WebFlux streamable transport Related to modelcontextprotocol#72 Signed-off-by: Christian Tzolov <[email protected]>

- Enhance McpStreamableServerSession error handling with proper JSON-RPC error responses - Add mcp-spring-webflux test dependency to webmvc module - Refactor WebMvcStreamableIntegrationTests to use parameterized tests - Support testing with both HttpClient and WebFlux transports - Add WebClientStreamableHttpTransport integration - Improve error handling in McpStreamableServerSession - Add proper timeout configurations for test clients - Clean up test structure and imports organization This enables comprehensive testing of WebMVC functionality with multiple transport mechanisms, ensuring compatibility across different client types. Signed-off-by: Christian Tzolov <[email protected]>

…ble transport - Add ReentrantLock synchronization to prevent race conditions in concurrent sseBuilder usage - Add volatile closed flag to track session state and prevent operations on closed sessions - Move SSE onComplete callback to properly close listening stream when connection completes - Refactor closeGracefully to delegate to close() method for consistent cleanup - Update class documentation to reflect thread-safety guarantees This ensures safe concurrent access to SSE builder and proper cleanup of streaming resources. Signed-off-by: Christian Tzolov <[email protected]>

… class - Extract common test logic from WebMvcSseIntegrationTests and WebMvcStreamableIntegrationTests into AbstractMcpClientServerIntegrationTests - Add json-unit-assertj dependency to mcp-test module for JSON assertion support - Make McpServer.SyncSpecification abstract to enforce proper inheritance - Remove duplicate test implementations (~2000+ lines of code deduplicated) - Maintain parameterized testing across different client transport types (httpclient, webflux) This refactoring eliminates significant code duplication between Spring WebMVC integration test classes while maintaining full test coverage and functionality. Signed-off-by: Christian Tzolov <[email protected]>

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

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

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]>

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

Open

7 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 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 mentioned this pull request Jul 22, 2025

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

Draft

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

chemicL and others added 16 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]>

improve webmvc streamable http server tests

7a2c476

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

adjust the McpTransportContext support

4702a2e

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

feat: add thread safety to SSE operations in WebMvcSseServerTransport…

cb26b5c

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

minor

fd8d7bb

Signed-off-by: Christian Tzolov <[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

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

5c09fa5

Streamable HTTP Server abstractions and HttpServlet, WebFlux, & WebMVC transport providers #290

Are you sure you want to change the base?

Streamable HTTP Server abstractions and HttpServlet, WebFlux, & WebMVC transport providers #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!

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