HttpServletStreamableServerTransportProvider: GET stream sends no status or headers until the first event · Issue #1155 · modelcontextprotocol/java-sdk · GitHub
Bug description
After initialize, a GET to the MCP endpoint with Accept: text/event-stream gets no status line and no headers. doGet sets the SSE headers and starts async but doesn't flush, so nothing is sent until the server writes its first event to the stream. If the server has nothing to send, the client never gets a response.
Clients that wait for headers time out. Node's fetch (undici) gives up after its default headersTimeout of 300 s with UND_ERR_HEADERS_TIMEOUT. mcp-remote then retries twice and stops ("Maximum reconnection attempts (2) exceeded"). After that the server has no stream to the client, and server-initiated requests fail with Stream unavailable for session ... (see also #1061).
With keepAliveInterval set, the first ping sends the headers, but only after one interval.
The spec says the server must either return Content-Type: text/event-stream for this GET or return 405 (Streamable HTTP, 2025-11-25).
Environment
Where it was seen: mcp-core 1.1.1, Spring Boot 4.0.5 (embedded Tomcat), Java 25.0.3, macOS 27.0.1. Client: Claude Desktop through mcp-remote 0.14.3, protocol 2025-11-25.
Reproduced with the test below: mcp-core 1.1.1 and 2.0.1, tomcat-embed-core 11.0.22, JDK 26.0.1, macOS 14.7.4. The doGet code is the same on main (1cf7903).
No keep-alive configured.
Steps to reproduce
POST initialize and note the Mcp-Session-Id.
POST notifications/initialized. You get 202.
GET the endpoint with Accept: text/event-stream and the session ID.
Expected behavior
200 with Content-Type: text/event-stream sent as soon as the GET stream opens, before any event is ready.
Minimal Complete Reproducible example
Dependencies: io.modelcontextprotocol.sdk:mcp, org.apache.tomcat.embed:tomcat-embed-core:11.0.22, org.junit.jupiter:junit-jupiter. The test fails with java.util.concurrent.TimeoutException on 1.1.1 and 2.0.1. If .keepAliveInterval(Duration.ofSeconds(1)) is added to the builder, it passes: the headers arrive with the first ping.
Confirmed and well-scoped - this is the classic "headers are written but never flushed" case, and your keepAliveInterval observation points right at it: with keep-alive, the first ping is what forces the flush.
Why it hangs
doGet sets Content-Type: text/event-stream and starts the async dispatch, but the container only commits the response (status line + headers) when the first bytes are written to the output stream. With no initial event and no keep-alive ping, the response stays in the "not yet committed" state indefinitely. The client is therefore waiting on headers that the server has already logically decided to send - it just has not been flushed.
This is why undici's UND_ERR_HEADERS_TIMEOUT is what you see rather than a body timeout: the client never got past the header phase.
Direction for the fix
Two changes, either of which resolves it, both worth doing:
Flush immediately after setting the headers. In a servlet-based transport, response.flushBuffer() after setHeader/setContentType commits the headers without writing an event. That satisfies the spec requirement to send Content-Type: text/event-stream as soon as the stream opens, and makes the client's header wait terminate.
Bound the open-but-idle stream. The spec permits returning 405 when the server does not offer a GET stream, and permits closing the stream when it has nothing to send. A zero-event GET that never terminates is the worst case for clients that retry - it burns a connection slot and, as you noted, exhausts mcp-remote's reconnect budget.
One subtlety on change (1): flushing at open changes the semantics of mcp-remote's reconnect logic. Once headers arrive, the client considers the stream established, so subsequent closes are treated as disconnects to retry rather than connection failures. That is generally the behavior you want, but it means the keep-alive interval should be set deliberately rather than left at zero, otherwise idle proxies may drop the connection and trigger the retry storm you are trying to avoid.
Test to lock it in
Your StreamableGetStreamHeadersTest is the right shape. Asserting on the Content-Type header arriving within a short deadline (rather than waiting for the default 300s) makes the regression catch the specific failure - the current test passing only with keepAliveInterval(1s) is exactly the signal that the immediate-flush path is missing.
This matches a transport divergence we track across the MCP SDKs: SSE semantics differ enough between the Java, Python and TypeScript streamable transports that "it works in one, hangs in another" is common. Keeping the header-commit point explicit in each implementation is what makes them behave the same - there is a write-up of the pattern at https://corpusiq.io if useful context.
Good catch - the doGet flush omission is a real spec deviation, not just a client-timeout nuisance.
Activity
Ben-Home commented on Oct 1, 2026
Confirmed and well-scoped - this is the classic "headers are written but never flushed" case, and your keepAliveInterval observation points right at it: with keep-alive, the first ping is what forces the flush.
Why it hangs
doGet sets Content-Type: text/event-stream and starts the async dispatch, but the container only commits the response (status line + headers) when the first bytes are written to the output stream. With no initial event and no keep-alive ping, the response stays in the "not yet committed" state indefinitely. The client is therefore waiting on headers that the server has already logically decided to send - it just has not been flushed.
This is why undici's UND_ERR_HEADERS_TIMEOUT is what you see rather than a body timeout: the client never got past the header phase.
Direction for the fix
Two changes, either of which resolves it, both worth doing:
Flush immediately after setting the headers. In a servlet-based transport, response.flushBuffer() after setHeader/setContentType commits the headers without writing an event. That satisfies the spec requirement to send Content-Type: text/event-stream as soon as the stream opens, and makes the client's header wait terminate.
Bound the open-but-idle stream. The spec permits returning 405 when the server does not offer a GET stream, and permits closing the stream when it has nothing to send. A zero-event GET that never terminates is the worst case for clients that retry - it burns a connection slot and, as you noted, exhausts mcp-remote's reconnect budget.
One subtlety on change (1): flushing at open changes the semantics of mcp-remote's reconnect logic. Once headers arrive, the client considers the stream established, so subsequent closes are treated as disconnects to retry rather than connection failures. That is generally the behavior you want, but it means the keep-alive interval should be set deliberately rather than left at zero, otherwise idle proxies may drop the connection and trigger the retry storm you are trying to avoid.
Test to lock it in
Your StreamableGetStreamHeadersTest is the right shape. Asserting on the Content-Type header arriving within a short deadline (rather than waiting for the default 300s) makes the regression catch the specific failure - the current test passing only with keepAliveInterval(1s) is exactly the signal that the immediate-flush path is missing.
This matches a transport divergence we track across the MCP SDKs: SSE semantics differ enough between the Java, Python and TypeScript streamable transports that "it works in one, hangs in another" is common. Keeping the header-commit point explicit in each implementation is what makes them behave the same - there is a write-up of the pattern at https://corpusiq.io if useful context.
Good catch - the doGet flush omission is a real spec deviation, not just a client-timeout nuisance.
Add a stateless server for MCP 2026-07-28
Add a stateless server for MCP 2026-07-28
Modern stateless server for MCP 2026-07-28 (#1170)