Skip to content

Close servlet streamable HTTP transports on async lifecycle events#1027

Open
lxq19991111 wants to merge 1 commit into
modelcontextprotocol:mainfrom
lxq19991111:fix/streamable-http-async-lifecycle
Open

Close servlet streamable HTTP transports on async lifecycle events#1027
lxq19991111 wants to merge 1 commit into
modelcontextprotocol:mainfrom
lxq19991111:fix/streamable-http-async-lifecycle

Conversation

@lxq19991111

Copy link
Copy Markdown

Summary

Register servlet async lifecycle cleanup for Streamable HTTP SSE transports created by
HttpServletStreamableServerTransportProvider.

This makes replay GET streams and POST streaming responses close their current transport when the servlet async
context completes, times out, or errors. It also routes SSE write failures through the transport close() path
instead of directly removing the logical MCP session.

Motivation

The core servlet Streamable HTTP transport can create async SSE responses whose lifecycle is not consistently wired
back to SDK transport cleanup. If a client disconnects, the server-side socket can remain open until a later write
failure, container timeout, or server shutdown.

In practice, this can leave server-side sockets in CLOSE-WAIT because the remote peer has sent FIN but the server
application has not completed the corresponding servlet async response. Since these streams use AsyncContext with no
timeout, the transport should explicitly clean up the current stream when servlet async lifecycle events indicate
completion, timeout, or error.

This PR intentionally focuses on the MCP Java SDK core servlet transport. It does not add session TTL, keep-alive
failed-ping eviction, or any Spring-specific WebMVC follow-up.

Changes

  • Add a shared servlet async lifecycle listener helper.
  • Register async lifecycle cleanup for replay GET streams.
  • Reuse the same cleanup helper for GET listening streams.
  • Register async lifecycle cleanup for POST streaming responses.
  • Close replay and POST streaming transports through the transport close() path on handling failures.
  • Close only the current transport on SSE write failure instead of removing the logical MCP session.
  • Add focused unit coverage for GET listening cleanup, GET replay cleanup, POST streaming response cleanup, and write-
    failure behavior.

Rationale

A TCP/SSE stream lifecycle is not the same as an MCP logical session lifecycle. A write failure or client disconnect
proves that the current HTTP/SSE transport is no longer usable, but it does not necessarily mean the whole MCP session
should be removed from the session registry.

For that reason, this change closes the current transport and completes the associated servlet async context, while
leaving session eviction to existing protocol-level paths such as DELETE, server shutdown, or future keep-alive/
session-expiration work.

The async listener reuses the existing stream/transport close paths. These close paths are guarded and idempotent, so
cleanup can be triggered consistently from servlet async completion, timeout, error, and write-failure paths.

Testing

Ran the focused mcp-core test class:

mvn -pl mcp-core -Dtest=HttpServletStreamableServerTransportProviderTests -DforkCount=0 test

Result:

Tests run: 4, Failures: 0, Errors: 0, Skipped: 0

The added tests cover:

- GET listening stream async error closes the listening stream.
- GET replay request async error closes the current transport.
- POST streaming response async error closes the current transport.
- SSE write failure closes only the current transport and does not remove the logical MCP session.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant