Skip to content

Commit f7cbabf

Browse files
committed
[Doc] Restructure README Usage section to align heading granularity
Group the Rails (mount) and Rails (controller) examples under a new `Streamable HTTP Transport` heading so they sit one level below the transport-type headings instead of alongside `Stdio Transport`. Also move the single-process and sticky-sessions caveat up to the `Streamable HTTP Transport` section since it applies to both Rails integration styles rather than only the controller approach.
1 parent 66d0722 commit f7cbabf

File tree

1 file changed

+24
-14
lines changed

1 file changed

+24
-14
lines changed

README.md

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,24 @@ $ ruby examples/stdio_server.rb
104104
{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"example_tool","arguments":{"message":"Hello"}}}
105105
```
106106

107-
#### Rails (mount)
107+
#### Streamable HTTP Transport
108+
109+
`MCP::Server::Transports::StreamableHTTPTransport` is a standard Rack app, so it can be mounted in any Rack-compatible framework.
110+
The following examples show two common integration styles in Rails.
111+
112+
> [!IMPORTANT]
113+
> `MCP::Server::Transports::StreamableHTTPTransport` stores session and SSE stream state in memory,
114+
> so it must run in a single process. Use a single-process server (e.g., Puma with `workers 0`).
115+
> Multi-process configurations (Unicorn, or Puma with `workers > 0`) fork separate processes that
116+
> do not share memory, which breaks session management and SSE connections.
117+
>
118+
> When running multiple server instances behind a load balancer, configure your load balancer to use
119+
> sticky sessions (session affinity) so that requests with the same `Mcp-Session-Id` header are always
120+
> routed to the same instance.
121+
>
122+
> Stateless mode (`stateless: true`) does not use sessions and works with any server configuration.
123+
124+
##### Rails (mount)
108125

109126
`StreamableHTTPTransport` is a Rack app that can be mounted directly in Rails routes:
110127

@@ -125,7 +142,12 @@ Rails.application.routes.draw do
125142
end
126143
```
127144

128-
#### Rails (controller)
145+
`mount` directs all HTTP methods on `/mcp` to the transport. `StreamableHTTPTransport` internally dispatches
146+
`POST` (JSON-RPC requests), `GET` (SSE stream for server-to-client messages), and `DELETE` (session termination) per
147+
the [MCP Streamable HTTP transport spec](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http),
148+
so no additional route configuration is needed.
149+
150+
##### Rails (controller)
129151

130152
While the mount approach creates a single server at boot time, the controller approach creates a new server per request.
131153
This allows you to customize tools, prompts, or configuration based on the request (e.g., different tools per route).
@@ -153,18 +175,6 @@ class McpController < ActionController::API
153175
end
154176
```
155177

156-
> [!IMPORTANT]
157-
> `MCP::Server::Transports::StreamableHTTPTransport` stores session and SSE stream state in memory,
158-
> so it must run in a single process. Use a single-process server (e.g., Puma with `workers 0`).
159-
> Multi-process configurations (Unicorn, or Puma with `workers > 0`) fork separate processes that
160-
> do not share memory, which breaks session management and SSE connections.
161-
>
162-
> When running multiple server instances behind a load balancer, configure your load balancer to use
163-
> sticky sessions (session affinity) so that requests with the same `Mcp-Session-Id` header are always
164-
> routed to the same instance.
165-
>
166-
> Stateless mode (`stateless: true`) does not use sessions and works with any server configuration.
167-
168178
### Configuration
169179

170180
The gem can be configured using the `MCP.configure` block:

0 commit comments

Comments
 (0)