From 9ebb42a5364fad3f59e814b2026baf7393538eec Mon Sep 17 00:00:00 2001 From: Koichi ITO Date: Fri, 3 Apr 2026 20:42:59 +0900 Subject: [PATCH] [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. --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 651c2ef8..da6f0ef8 100644 --- a/README.md +++ b/README.md @@ -303,6 +303,13 @@ transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session ### Usage +> [!IMPORTANT] +> `MCP::Server::Transports::StreamableHTTPTransport` stores session and SSE stream state in memory, +> so it must run in a single process. Use a single-process server (e.g., Puma with `workers 0`). +> Multi-process configurations (Unicorn, or Puma with `workers > 0`) fork separate processes that +> do not share memory, which breaks session management and SSE connections. +> Stateless mode (`stateless: true`) does not use sessions and works with any server configuration. + #### Rails Controller When added to a Rails controller on a route that handles POST requests, your server will be compliant with non-streaming