Skip to content

Commit aca8e75

Browse files
committed
Streamable HTTP: flush SSE headers early
Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>
1 parent 88ebcb7 commit aca8e75

4 files changed

Lines changed: 130 additions & 70 deletions

File tree

‎mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletResponseUtils.java‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
package io.modelcontextprotocol.server.transport;
66

7+
import java.io.IOException;
8+
79
import jakarta.servlet.http.HttpServletResponse;
810

911
/**
@@ -15,22 +17,23 @@ final class HttpServletResponseUtils {
1517

1618
private static final String TEXT_EVENT_STREAM = "text/event-stream";
1719

18-
private static final String UTF_8 = "UTF-8";
19-
2020
private HttpServletResponseUtils() {
2121
}
2222

2323
/**
24-
* Prepares the response for streaming Server-Sent Events: sets the content type,
25-
* character encoding and the headers that keep intermediaries from caching,
26-
* transforming or buffering the stream.
24+
* Prepares the response for streaming Server-Sent Events: sets the content type and
25+
* the headers that keep intermediaries from caching, transforming or buffering the
26+
* stream.
27+
* <p>
28+
* The headers are flushed immediately so the client receives something even when the
29+
* server delays sending data.
2730
* @param response The HTTP servlet response
2831
*/
29-
static void prepareSseResponse(HttpServletResponse response) {
32+
static void prepareSseResponse(HttpServletResponse response) throws IOException {
3033
response.setContentType(TEXT_EVENT_STREAM);
31-
response.setCharacterEncoding(UTF_8);
3234
response.setHeader("Cache-Control", "no-cache, no-transform");
3335
response.setHeader("X-Accel-Buffering", "no");
36+
response.flushBuffer();
3437
}
3538

3639
}

‎mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -300,13 +300,13 @@ protected void doGet(HttpServletRequest request, HttpServletResponse response)
300300
return;
301301
}
302302

303-
HttpServletResponseUtils.prepareSseResponse(response);
304-
305303
String sessionId = UUID.randomUUID().toString();
306304
AsyncContext asyncContext = request.startAsync();
307305
asyncContext.setTimeout(0);
308306

307+
response.setCharacterEncoding(UTF_8);
309308
PrintWriter writer = response.getWriter();
309+
HttpServletResponseUtils.prepareSseResponse(response);
310310

311311
// Create a new session transport
312312
HttpServletMcpSessionTransport sessionTransport = new HttpServletMcpSessionTransport(sessionId, asyncContext,

‎mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java‎

Lines changed: 59 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -425,14 +425,27 @@ protected void doGet(HttpServletRequest request, HttpServletResponse response)
425425

426426
McpTransportContext transportContext = this.contextExtractor.extract(request);
427427

428+
PrintWriter writer;
429+
AsyncContext asyncContext;
428430
try {
429-
HttpServletResponseUtils.prepareSseResponse(response);
430-
431-
AsyncContext asyncContext = request.startAsync();
431+
response.setCharacterEncoding(UTF_8);
432+
writer = response.getWriter();
433+
asyncContext = request.startAsync();
432434
asyncContext.setTimeout(0);
435+
}
436+
catch (Exception e) {
437+
// Nothing has been written yet, so an error status can still be sent
438+
logger.error("Failed to start the GET stream for session {}: {}", sessionId, e.getMessage());
439+
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
440+
return;
441+
}
433442

434-
HttpServletStreamableMcpSessionTransport sessionTransport = new HttpServletStreamableMcpSessionTransport(
435-
sessionId, asyncContext, response.getWriter());
443+
HttpServletStreamableMcpSessionTransport sessionTransport = new HttpServletStreamableMcpSessionTransport(
444+
sessionId, asyncContext, writer);
445+
try {
446+
// Send headers as soon as the stream is open: even if the server doesn't send
447+
// data, the client will receive the headers
448+
HttpServletResponseUtils.prepareSseResponse(response);
436449

437450
// Replay the messages the client missed while its stream was broken
438451
String lastEventId = request.getHeader(HttpHeaders.LAST_EVENT_ID);
@@ -450,9 +463,14 @@ protected void doGet(HttpServletRequest request, HttpServletResponse response)
450463

451464
registerAsyncLifecycle(asyncContext, sessionId, listeningStream::releaseTransport);
452465
}
466+
catch (IOException e) {
467+
// Only flushing the headers throws IOException
468+
logger.debug("Failed to send the GET stream headers for session {}: {}", sessionId, e.getMessage());
469+
sessionTransport.close();
470+
}
453471
catch (Exception e) {
454472
logger.error("Failed to handle GET request for session {}: {}", sessionId, e.getMessage());
455-
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
473+
sessionTransport.close();
456474
}
457475
}
458476

@@ -598,27 +616,48 @@ else if (message instanceof McpSchema.JSONRPCNotification jsonrpcNotification) {
598616
}
599617
else if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
600618
// For streaming responses, we need to return SSE
601-
HttpServletResponseUtils.prepareSseResponse(response);
602-
603-
AsyncContext asyncContext = request.startAsync();
604-
asyncContext.setTimeout(0);
619+
PrintWriter writer;
620+
AsyncContext asyncContext;
621+
try {
622+
response.setCharacterEncoding(UTF_8);
623+
writer = response.getWriter();
624+
asyncContext = request.startAsync();
625+
asyncContext.setTimeout(0);
626+
}
627+
catch (Exception e) {
628+
// Nothing has been written yet, so an error status can still be sent
629+
logger.error("Failed to start the request stream for session {}: {}", sessionId, e.getMessage());
630+
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
631+
return;
632+
}
605633

606634
HttpServletStreamableMcpSessionTransport sessionTransport = new HttpServletStreamableMcpSessionTransport(
607-
sessionId, asyncContext, response.getWriter());
608-
609-
// The listener is given the stream rather than its transport, so that the
610-
// end of the connection detaches the stream from the session instead of
611-
// only dropping the socket: a stream outliving its connection keeps the
612-
// session looking busy and spares it from the sweeper
613-
McpStreamableServerSession.McpStreamableServerSessionStream responseStream = session
614-
.responseStream(sessionTransport);
615-
registerAsyncLifecycle(asyncContext, sessionId, responseStream::releaseTransport);
616-
635+
sessionId, asyncContext, writer);
617636
try {
637+
// Send headers as soon as the stream is open: even if the server
638+
// doesn't send
639+
// data, the client will receive the headers
640+
HttpServletResponseUtils.prepareSseResponse(response);
641+
642+
// The listener is given the stream rather than its transport, so that
643+
// the end of the connection detaches the stream from the session
644+
// instead of only dropping the socket: a stream outliving its
645+
// connection keeps the session looking busy and spares it from the
646+
// sweeper
647+
McpStreamableServerSession.McpStreamableServerSessionStream responseStream = session
648+
.responseStream(sessionTransport);
649+
registerAsyncLifecycle(asyncContext, sessionId, responseStream::releaseTransport);
650+
618651
responseStream.handle(jsonrpcRequest)
619652
.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
620653
.block();
621654
}
655+
catch (IOException e) {
656+
// Only flushing the headers throws IOException
657+
logger.debug("Failed to send the request stream headers for session {}: {}", sessionId,
658+
e.getMessage());
659+
sessionTransport.close();
660+
}
622661
catch (Exception e) {
623662
logger.error("Failed to handle request stream: {}", e.getMessage());
624663
// The transport may already have completed the async context, when

‎mcp-test/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java‎

Lines changed: 59 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
import java.util.Queue;
2020
import java.util.concurrent.CompletableFuture;
2121
import java.util.concurrent.ConcurrentLinkedQueue;
22+
import java.util.concurrent.TimeUnit;
2223
import java.util.concurrent.atomic.AtomicBoolean;
2324
import java.util.concurrent.atomic.AtomicReference;
2425
import java.util.function.Function;
@@ -39,6 +40,7 @@
3940
import io.modelcontextprotocol.spec.HttpHeaders;
4041
import io.modelcontextprotocol.spec.McpSchema;
4142
import io.modelcontextprotocol.util.KeepAliveScheduler;
43+
import io.modelcontextprotocol.util.ToolsUtils;
4244
import jakarta.servlet.http.HttpServletRequest;
4345
import jakarta.servlet.http.HttpServletResponse;
4446
import org.apache.catalina.LifecycleException;
@@ -55,6 +57,7 @@
5557
import org.slf4j.LoggerFactory;
5658
import reactor.core.publisher.Flux;
5759
import reactor.core.publisher.Mono;
60+
import reactor.core.publisher.Sinks;
5861
import reactor.core.scheduler.Schedulers;
5962
import reactor.test.StepVerifier;
6063
import reactor.test.scheduler.VirtualTimeScheduler;
@@ -205,8 +208,9 @@ void testMissingHandlerReturnsMethodNotFoundError() {
205208
}
206209

207210
@Test
208-
void listeningStreamHasStreamingHeaders() throws Exception {
209-
prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
211+
void listeningStreamSendsHeadersBeforeFirstEvent() throws Exception {
212+
// Without keep-alive nothing is written, so only an early flush sends the headers
213+
withTransportProvider(null, null);
210214
var sessionId = initializeSession(httpClient);
211215

212216
var get = HttpRequest.newBuilder()
@@ -216,8 +220,10 @@ void listeningStreamHasStreamingHeaders() throws Exception {
216220
.GET()
217221
.build();
218222

219-
var response = httpClient.send(get, HttpResponse.BodyHandlers.ofInputStream());
223+
// Completes once the headers arrive, before any event
224+
var response = httpClient.sendAsync(get, HttpResponse.BodyHandlers.ofInputStream()).get(5, TimeUnit.SECONDS);
220225
try {
226+
assertThat(response.statusCode()).isEqualTo(HttpServletResponse.SC_OK);
221227
assertSseHeaders(response);
222228
}
223229
finally {
@@ -226,17 +232,28 @@ void listeningStreamHasStreamingHeaders() throws Exception {
226232
}
227233

228234
@Test
229-
void toolCallSseResponseHasStreamingHeaders() throws Exception {
230-
prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
231-
.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
235+
void toolCallSseResponseSendsHeadersBeforeResult() throws Exception {
236+
mcpServerTransportProvider.closeGracefully().block();
237+
mcpServerTransportProvider = HttpServletStreamableServerTransportProvider.builder()
238+
.contextExtractor(TEST_CONTEXT_EXTRACTOR)
239+
.mcpEndpoint(MESSAGE_ENDPOINT)
240+
// Without keep-alive nothing is written until the tool returns
241+
.keepAliveInterval(null)
242+
.sessionSweepInterval(null)
243+
.build();
244+
245+
mcpServlet.setDelegate(mcpServerTransportProvider);
246+
247+
// Returns once the test completes toolResult
248+
Sinks.One<McpSchema.CallToolResult> toolResult = Sinks.one();
249+
prepareAsyncServerBuilder().capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
232250
.tools(McpServerFeatures.AsyncToolSpecification.builder()
233-
.tool(McpSchema.Tool.builder("echo", EMPTY_JSON_SCHEMA).description("returns immediately").build())
234-
.callHandler((exchange,
235-
request) -> Mono.just(McpSchema.CallToolResult.builder()
236-
.content(List.of(McpSchema.TextContent.builder("ok").build()))
237-
.isError(false)
238-
.build()))
251+
.tool(McpSchema.Tool.builder("slow", ToolsUtils.EMPTY_JSON_SCHEMA)
252+
.description("returns when released")
253+
.build())
254+
.callHandler((exchange, request) -> toolResult.asMono())
239255
.build())
256+
.serverInfo("test-server", "1.0.0")
240257
.build();
241258
var sessionId = initializeSession(httpClient);
242259

@@ -247,15 +264,27 @@ void toolCallSseResponseHasStreamingHeaders() throws Exception {
247264
.header(HttpHeaders.MCP_SESSION_ID, sessionId)
248265
.POST(HttpRequest.BodyPublishers
249266
.ofString("{\"jsonrpc\":\"2.0\",\"id\":\"call-1\",\"method\":\"tools/call\","
250-
+ "\"params\":{\"name\":\"echo\",\"arguments\":{}}}"))
267+
+ "\"params\":{\"name\":\"slow\",\"arguments\":{}}}"))
251268
.build();
252269

253-
var response = httpClient.send(post, HttpResponse.BodyHandlers.ofInputStream());
254270
try {
255-
assertSseHeaders(response);
271+
// Completes once the headers arrive, before any event
272+
var response = httpClient.sendAsync(post, HttpResponse.BodyHandlers.ofInputStream())
273+
.get(5, TimeUnit.SECONDS);
274+
try {
275+
assertThat(response.statusCode()).isEqualTo(HttpServletResponse.SC_OK);
276+
assertSseHeaders(response);
277+
}
278+
finally {
279+
response.body().close();
280+
}
256281
}
257282
finally {
258-
response.body().close();
283+
// Release the Tomcat thread blocked in doPost until the tool returns
284+
toolResult.tryEmitValue(McpSchema.CallToolResult.builder()
285+
.content(List.of(McpSchema.TextContent.builder("done").build()))
286+
.isError(false)
287+
.build());
259288
}
260289
}
261290

@@ -563,10 +592,6 @@ void sessionEvictionAfterReleasingStream() {
563592
var sessionId = initializeSession(httpClient);
564593
var clientStream = openListeningStream(httpClient, sessionId, null);
565594
awaitClientStreamEstablished();
566-
// "prep" the client so we can close the stream by sending data: the
567-
// subscription
568-
// in the clientStream is only present when the client has received data
569-
awaitNotification(clientStream.events());
570595
virtualTime.advanceTimeBy(SESSION_SWEEP_INTERVAL.multipliedBy(2));
571596
assertThat(postNotification(httpClient, sessionId)).as("Session should be active when a stream is open")
572597
.isEqualTo(HttpServletResponse.SC_ACCEPTED);
@@ -621,17 +646,22 @@ void sessionIsEvictedWhenTheClientAbortsAResponseStream() {
621646
try {
622647
withTransportProvider(null, SESSION_SWEEP_INTERVAL);
623648
var toolEmissionInterval = Duration.ofMillis(10);
649+
var toolCalled = new AtomicBoolean();
624650
prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
625651
.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
626652
.tools(McpServerFeatures.AsyncToolSpecification.builder()
627653
.tool(McpSchema.Tool.builder("hangs", EMPTY_JSON_SCHEMA).description("never returns").build())
628-
.callHandler((exchange, request) -> Flux
629-
.interval(toolEmissionInterval, toolEmissionInterval, Schedulers.newSingle("test-tool"))
630-
.flatMap(tick -> exchange.loggingNotification(McpSchema.LoggingMessageNotification.builder()
631-
.level(McpSchema.LoggingLevel.INFO)
632-
.data("x".repeat(64 * 1024))
633-
.build()))
634-
.then(Mono.<McpSchema.CallToolResult>never()))
654+
.callHandler((exchange, request) -> {
655+
toolCalled.set(true);
656+
// Keep writing: a disconnect is only noticed on write
657+
return Flux
658+
.interval(toolEmissionInterval, toolEmissionInterval, Schedulers.newSingle("test-tool"))
659+
.flatMap(tick -> exchange.loggingNotification(McpSchema.LoggingMessageNotification.builder()
660+
.level(McpSchema.LoggingLevel.INFO)
661+
.data("x".repeat(64 * 1024))
662+
.build()))
663+
.then(Mono.<McpSchema.CallToolResult>never());
664+
})
635665
.build())
636666
.build();
637667
var sessionId = initializeSession(httpClient);
@@ -640,18 +670,7 @@ void sessionIsEvictedWhenTheClientAbortsAResponseStream() {
640670
// stream for as long as the call is in flight
641671
var responseStream = postToolCall(httpClient, sessionId, "hangs");
642672

643-
await().atMost(Duration.ofSeconds(5))
644-
.pollDelay(Duration.ZERO)
645-
.pollInterval(Duration.ofMillis(10))
646-
.untilAsserted(() -> {
647-
// We do this in a loop for the wire-side of the connection - data has
648-
// to be buffered then flushed
649-
650-
// Advance time so the tool emits some data
651-
virtualTime.advanceTimeBy(toolEmissionInterval);
652-
// Verify the data is received
653-
assertThat(responseStream.events()).anyMatch(line -> line.contains("notifications/message"));
654-
});
673+
await().atMost(Duration.ofSeconds(5)).pollInterval(Duration.ofMillis(20)).untilTrue(toolCalled);
655674
virtualTime.advanceTimeBy(SESSION_SWEEP_INTERVAL.multipliedBy(2));
656675
assertThat(postNotification(httpClient, sessionId)).as("Session with POST stream is active")
657676
.isEqualTo(HttpServletResponse.SC_ACCEPTED);
@@ -781,8 +800,7 @@ record StreamResponse(CompletableFuture<Void> streamFuture, Queue<String> events
781800
AtomicReference<InputStream> streamRef) {
782801

783802
void closeStream() {
784-
// Close listening stream. We retry a few times in case the stream was not
785-
// established on the first try
803+
// streamRef is set asynchronously, once the headers arrive
786804
await().pollDelay(Duration.ZERO).atMost(Duration.ofSeconds(1)).until(() -> {
787805
var stream = streamRef.get();
788806
if (stream != null) {

0 commit comments

Comments
 (0)