Skip to content

Commit 9ebb42a

Browse files
committed
[Doc] Clarify that StreamableHTTPTransport requires a single-process server
## Motivation and Context `StreamableHTTPTransport` stores session and SSE stream state in memory using instance variables (`@sessions`, `@mutex`). This design requires all HTTP requests to be handled within the same process to share state. Process-based servers like Unicorn fork separate worker processes that do not share memory, which breaks session management and SSE connections. This requirement is not obvious from the current documentation. ## How Has This Been Tested? Documentation-only change. ## Breaking Changes None.
1 parent 6669601 commit 9ebb42a

File tree

1 file changed

+7
-0
lines changed

1 file changed

+7
-0
lines changed

README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -303,6 +303,13 @@ transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session
303303

304304
### Usage
305305

306+
> [!IMPORTANT]
307+
> `MCP::Server::Transports::StreamableHTTPTransport` stores session and SSE stream state in memory,
308+
> so it must run in a single process. Use a single-process server (e.g., Puma with `workers 0`).
309+
> Multi-process configurations (Unicorn, or Puma with `workers > 0`) fork separate processes that
310+
> do not share memory, which breaks session management and SSE connections.
311+
> Stateless mode (`stateless: true`) does not use sessions and works with any server configuration.
312+
306313
#### Rails Controller
307314

308315
When added to a Rails controller on a route that handles POST requests, your server will be compliant with non-streaming

0 commit comments

Comments
 (0)