Skip to content

Commit f4961a8

Browse files
koickoic
committed
Make StreamableHTTPTransport a Rack application
## Motivation and Context Add `call(env)` to `StreamableHTTPTransport`, making it a Rack application that works with `mount`, `run`, and Rack middleware. Refactor examples to use Rack middleware classes for MCP logging instead of proc wrappers, demonstrating idiomatic Rack composition with the new `run(transport)` pattern. Update README.md with mount and controller integration patterns. Closes #59, #60 ## How Has This Been Tested? Added tests for `call(env)` as a Rack app. All tests pass. ## Breaking Change No breaking changes. All existing APIs are preserved: - `StreamableHTTPTransport.new(server)` continues to work as before. - `handle_request(request)` is unchanged. The new `call(env)` is a purely additive public method.
1 parent 1b8e45f commit f4961a8

File tree

6 files changed

+210
-104
lines changed

6 files changed

+210
-104
lines changed

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,6 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing
102102

103103
### Integration patterns
104104

105-
- **Rails controllers**: Use `server.handle_json(request.body.read)` for HTTP endpoints
105+
- **Rails/Rack apps**: Mount `StreamableHTTPTransport` as a Rack app (e.g., `mount transport => "/mcp"`)
106106
- **Command-line tools**: Use `StdioTransport.new(server).open` for CLI applications
107-
- **HTTP services**: Use `StreamableHttpTransport` for web-based servers
107+
- **HTTP services**: Use `StreamableHTTPTransport` for web-based servers

‎README.md‎

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -301,14 +301,34 @@ transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, statele
301301

302302
### Usage
303303

304-
#### Rails Controller
304+
#### Rails (mount)
305305

306-
When added to a Rails controller on a route that handles POST requests, your server will be compliant with non-streaming
307-
[Streamable HTTP](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http) transport
308-
requests.
306+
`StreamableHTTPTransport` is a Rack app that can be mounted directly in Rails routes:
309307

310-
You can use `StreamableHTTPTransport#handle_request` to handle requests with proper HTTP
311-
status codes (e.g., 202 Accepted for notifications).
308+
```ruby
309+
# config/routes.rb
310+
server = MCP::Server.new(
311+
name: "my_server",
312+
title: "Example Server Display Name",
313+
version: "1.0.0",
314+
instructions: "Use the tools of this server as a last resort",
315+
tools: [SomeTool, AnotherTool],
316+
prompts: [MyPrompt],
317+
)
318+
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
319+
server.transport = transport
320+
321+
Rails.application.routes.draw do
322+
mount transport => "/mcp"
323+
end
324+
```
325+
326+
#### Rails (controller)
327+
328+
While the mount approach creates a single server at boot time, the controller approach creates a new server per request.
329+
This allows you to customize tools, prompts, or configuration based on the request (e.g., different tools per route).
330+
331+
`StreamableHTTPTransport#handle_request` returns proper HTTP status codes (e.g., 202 Accepted for notifications):
312332

313333
```ruby
314334
class McpController < ActionController::Base

‎examples/http_server.rb‎

Lines changed: 40 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -96,52 +96,52 @@ def template(args, server_context:)
9696
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
9797
server.transport = transport
9898

99-
# Create a logger for MCP-specific logging
100-
mcp_logger = Logger.new($stdout)
101-
mcp_logger.formatter = proc do |_severity, _datetime, _progname, msg|
102-
"[MCP] #{msg}\n"
103-
end
99+
# Rack middleware for MCP-specific request/response logging.
100+
class McpRequestLogger
101+
def initialize(app)
102+
@app = app
103+
@logger = Logger.new($stdout)
104+
@logger.formatter = proc { |_severity, _datetime, _progname, msg| "[MCP] #{msg}\n" }
105+
end
106+
107+
def call(env)
108+
if env["REQUEST_METHOD"] == "POST"
109+
body = env["rack.input"].read
110+
env["rack.input"].rewind
104111

105-
# Create a Rack application with logging
106-
app = proc do |env|
107-
request = Rack::Request.new(env)
108-
109-
# Log MCP-specific details for POST requests
110-
if request.post?
111-
body = request.body.read
112-
request.body.rewind
113-
begin
114-
parsed_body = JSON.parse(body)
115-
mcp_logger.info("Request: #{parsed_body["method"]} (id: #{parsed_body["id"]})")
116-
mcp_logger.debug("Request body: #{JSON.pretty_generate(parsed_body)}")
117-
rescue JSON::ParserError
118-
mcp_logger.warn("Request body (raw): #{body}")
112+
begin
113+
parsed = JSON.parse(body)
114+
115+
@logger.info("Request: #{parsed["method"]} (id: #{parsed["id"]})")
116+
@logger.debug("Request body: #{JSON.pretty_generate(parsed)}")
117+
rescue JSON::ParserError
118+
@logger.warn("Request body (raw): #{body}")
119+
end
119120
end
120-
end
121121

122-
# Handle the request
123-
response = transport.handle_request(request)
124-
125-
# Log the MCP response details
126-
_, _, body = response
127-
if body.is_a?(Array) && !body.empty? && body.first
128-
begin
129-
parsed_response = JSON.parse(body.first)
130-
if parsed_response["error"]
131-
mcp_logger.error("Response error: #{parsed_response["error"]["message"]}")
132-
else
133-
mcp_logger.info("Response: #{parsed_response["result"] ? "success" : "empty"} (id: #{parsed_response["id"]})")
122+
status, headers, response_body = @app.call(env)
123+
124+
if response_body.is_a?(Array) && !response_body.empty? && response_body.first
125+
begin
126+
parsed = JSON.parse(response_body.first)
127+
128+
if parsed["error"]
129+
@logger.error("Response error: #{parsed["error"]["message"]}")
130+
else
131+
@logger.info("Response: #{parsed["result"] ? "success" : "empty"} (id: #{parsed["id"]})")
132+
end
133+
@logger.debug("Response body: #{JSON.pretty_generate(parsed)}")
134+
rescue JSON::ParserError
135+
@logger.warn("Response body (raw): #{response_body}")
134136
end
135-
mcp_logger.debug("Response body: #{JSON.pretty_generate(parsed_response)}")
136-
rescue JSON::ParserError
137-
mcp_logger.warn("Response body (raw): #{body}")
138137
end
139-
end
140138

141-
response
139+
[status, headers, response_body]
140+
end
142141
end
143142

144-
# Wrap the app with Rack middleware
143+
# Build the Rack application with middleware.
144+
# `StreamableHTTPTransport` responds to `call(env)`, so it can be used directly as a Rack app.
145145
rack_app = Rack::Builder.new do
146146
# Enable CORS to allow browser-based MCP clients (e.g., MCP Inspector)
147147
# WARNING: origins("*") allows all origins. Restrict this in production.
@@ -159,11 +159,10 @@ def template(args, server_context:)
159159

160160
# Use CommonLogger for standard HTTP request logging
161161
use(Rack::CommonLogger, Logger.new($stdout))
162-
163-
# Add other useful middleware
164162
use(Rack::ShowExceptions)
163+
use(McpRequestLogger)
165164

166-
run(app)
165+
run(transport)
167166
end
168167

169168
# Start the server

‎examples/streamable_http_server.rb‎

Lines changed: 49 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -65,70 +65,62 @@ def call(message:, delay: 0)
6565
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
6666
server.transport = transport
6767

68-
# Create a logger for MCP request/response logging
69-
mcp_logger = Logger.new($stdout)
70-
mcp_logger.formatter = proc do |_severity, _datetime, _progname, msg|
71-
"[MCP] #{msg}\n"
72-
end
68+
# Rack middleware for MCP request/response and SSE logging.
69+
class McpSseLogger
70+
def initialize(app)
71+
@app = app
72+
73+
@mcp_logger = Logger.new($stdout)
74+
@mcp_logger.formatter = proc { |_severity, _datetime, _progname, msg| "[MCP] #{msg}\n" }
75+
76+
@sse_logger = Logger.new($stdout)
77+
@sse_logger.formatter = proc { |severity, datetime, _progname, msg| "[SSE] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n" }
78+
end
7379

74-
# Create the Rack application
75-
app = proc do |env|
76-
request = Rack::Request.new(env)
77-
78-
# Log request details
79-
if request.post?
80-
body = request.body.read
81-
request.body.rewind
82-
begin
83-
parsed_body = JSON.parse(body)
84-
mcp_logger.info("Request: #{parsed_body["method"]} (id: #{parsed_body["id"]})")
85-
86-
# Log SSE-specific setup
87-
if parsed_body["method"] == "initialize"
88-
sse_logger.info("New client initializing session")
80+
def call(env)
81+
if env["REQUEST_METHOD"] == "POST"
82+
body = env["rack.input"].read
83+
env["rack.input"].rewind
84+
85+
begin
86+
parsed = JSON.parse(body)
87+
88+
@mcp_logger.info("Request: #{parsed["method"]} (id: #{parsed["id"]})")
89+
@sse_logger.info("New client initializing session") if parsed["method"] == "initialize"
90+
rescue JSON::ParserError
91+
@mcp_logger.warn("Invalid JSON in request")
8992
end
90-
rescue JSON::ParserError
91-
mcp_logger.warn("Invalid JSON in request")
93+
elsif env["REQUEST_METHOD"] == "GET"
94+
session_id = env["HTTP_MCP_SESSION_ID"] || Rack::Utils.parse_query(env["QUERY_STRING"])["sessionId"]
95+
96+
@sse_logger.info("SSE connection request for session: #{session_id}")
9297
end
93-
elsif request.get?
94-
session_id = request.env["HTTP_MCP_SESSION_ID"] ||
95-
Rack::Utils.parse_query(request.env["QUERY_STRING"])["sessionId"]
96-
sse_logger.info("SSE connection request for session: #{session_id}")
97-
end
9898

99-
# Handle the request
100-
response = transport.handle_request(request)
101-
102-
# Log response details
103-
status, headers, body = response
104-
if body.is_a?(Array) && !body.empty? && request.post?
105-
begin
106-
parsed_response = JSON.parse(body.first)
107-
if parsed_response["error"]
108-
mcp_logger.error("Response error: #{parsed_response["error"]["message"]}")
109-
elsif parsed_response["accepted"]
110-
# Response was sent via SSE
111-
server.notify_log_message(data: { details: "Response accepted and sent via SSE" }, level: "info")
112-
sse_logger.info("Response sent via SSE stream")
113-
else
114-
mcp_logger.info("Response: success (id: #{parsed_response["id"]})")
115-
116-
# Log session ID for initialization
117-
if headers["Mcp-Session-Id"]
118-
sse_logger.info("Session created: #{headers["Mcp-Session-Id"]}")
99+
status, headers, response_body = @app.call(env)
100+
101+
if response_body.is_a?(Array) && !response_body.empty? && env["REQUEST_METHOD"] == "POST"
102+
begin
103+
parsed = JSON.parse(response_body.first)
104+
105+
if parsed["error"]
106+
@mcp_logger.error("Response error: #{parsed["error"]["message"]}")
107+
else
108+
@mcp_logger.info("Response: success (id: #{parsed["id"]})")
109+
@sse_logger.info("Session created: #{headers["Mcp-Session-Id"]}") if headers["Mcp-Session-Id"]
119110
end
111+
rescue JSON::ParserError
112+
@mcp_logger.warn("Invalid JSON in response")
120113
end
121-
rescue JSON::ParserError
122-
mcp_logger.warn("Invalid JSON in response")
114+
elsif env["REQUEST_METHOD"] == "GET" && status == 200
115+
@sse_logger.info("SSE stream established")
123116
end
124-
elsif request.get? && status == 200
125-
sse_logger.info("SSE stream established")
126-
end
127117

128-
response
118+
[status, headers, response_body]
119+
end
129120
end
130121

131-
# Build the Rack application with middleware
122+
# Build the Rack application with middleware.
123+
# `StreamableHTTPTransport` responds to `call(env)`, so it can be used directly as a Rack app.
132124
rack_app = Rack::Builder.new do
133125
# Enable CORS to allow browser-based MCP clients (e.g., MCP Inspector)
134126
# WARNING: origins("*") allows all origins. Restrict this in production.
@@ -146,7 +138,9 @@ def call(message:, delay: 0)
146138

147139
use(Rack::CommonLogger, Logger.new($stdout))
148140
use(Rack::ShowExceptions)
149-
run(app)
141+
use(McpSseLogger)
142+
143+
run(transport)
150144
end
151145

152146
# Print usage instructions

‎lib/mcp/server/transports/streamable_http_transport.rb‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,15 @@
44
require "securerandom"
55
require_relative "../../transport"
66

7+
# This file is autoloaded only when `StreamableHTTPTransport` is referenced,
8+
# so the `rack` dependency does not affect `StdioTransport` users.
9+
begin
10+
require "rack"
11+
rescue LoadError
12+
raise LoadError, "The 'rack' gem is required to use the StreamableHTTPTransport. " \
13+
"Add it to your Gemfile: gem 'rack'"
14+
end
15+
716
module MCP
817
class Server
918
module Transports
@@ -21,6 +30,11 @@ def initialize(server, stateless: false)
2130
REQUIRED_GET_ACCEPT_TYPES = ["text/event-stream"].freeze
2231
STREAM_WRITE_ERRORS = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
2332

33+
# Rack app interface. This transport can be mounted as a Rack app.
34+
def call(env)
35+
handle_request(Rack::Request.new(env))
36+
end
37+
2438
def handle_request(request)
2539
case request.env["REQUEST_METHOD"]
2640
when "POST"

‎test/mcp/server/transports/streamable_http_transport_test.rb‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1325,6 +1325,85 @@ class StreamableHTTPTransportTest < ActiveSupport::TestCase
13251325
assert_equal(200, response[0])
13261326
end
13271327

1328+
test "call(env) works as a Rack app for POST requests" do
1329+
env = {
1330+
"REQUEST_METHOD" => "POST",
1331+
"PATH_INFO" => "/",
1332+
"rack.input" => StringIO.new({ jsonrpc: "2.0", method: "initialize", id: "init-1" }.to_json),
1333+
"CONTENT_TYPE" => "application/json",
1334+
"HTTP_ACCEPT" => "application/json, text/event-stream",
1335+
}
1336+
1337+
response = @transport.call(env)
1338+
assert_equal 200, response[0]
1339+
assert_equal "application/json", response[1]["Content-Type"]
1340+
1341+
body = JSON.parse(response[2][0])
1342+
assert_equal "2.0", body["jsonrpc"]
1343+
assert_equal "init-1", body["id"]
1344+
end
1345+
1346+
test "call(env) returns 405 for unsupported HTTP methods" do
1347+
env = {
1348+
"REQUEST_METHOD" => "PUT",
1349+
"PATH_INFO" => "/",
1350+
"rack.input" => StringIO.new(""),
1351+
}
1352+
1353+
response = @transport.call(env)
1354+
assert_equal 405, response[0]
1355+
end
1356+
1357+
test "call(env) handles GET SSE stream request" do
1358+
init_env = {
1359+
"REQUEST_METHOD" => "POST",
1360+
"PATH_INFO" => "/",
1361+
"rack.input" => StringIO.new({ jsonrpc: "2.0", method: "initialize", id: "init" }.to_json),
1362+
"CONTENT_TYPE" => "application/json",
1363+
"HTTP_ACCEPT" => "application/json, text/event-stream",
1364+
}
1365+
init_response = @transport.call(init_env)
1366+
session_id = init_response[1]["Mcp-Session-Id"]
1367+
1368+
get_env = {
1369+
"REQUEST_METHOD" => "GET",
1370+
"PATH_INFO" => "/",
1371+
"rack.input" => StringIO.new(""),
1372+
"HTTP_ACCEPT" => "text/event-stream",
1373+
"HTTP_MCP_SESSION_ID" => session_id,
1374+
}
1375+
1376+
response = @transport.call(get_env)
1377+
assert_equal 200, response[0]
1378+
assert_equal "text/event-stream", response[1]["Content-Type"]
1379+
assert response[2].is_a?(Proc)
1380+
end
1381+
1382+
test "call(env) handles DELETE session request" do
1383+
init_env = {
1384+
"REQUEST_METHOD" => "POST",
1385+
"PATH_INFO" => "/",
1386+
"rack.input" => StringIO.new({ jsonrpc: "2.0", method: "initialize", id: "init" }.to_json),
1387+
"CONTENT_TYPE" => "application/json",
1388+
"HTTP_ACCEPT" => "application/json, text/event-stream",
1389+
}
1390+
init_response = @transport.call(init_env)
1391+
session_id = init_response[1]["Mcp-Session-Id"]
1392+
1393+
delete_env = {
1394+
"REQUEST_METHOD" => "DELETE",
1395+
"PATH_INFO" => "/",
1396+
"rack.input" => StringIO.new(""),
1397+
"HTTP_MCP_SESSION_ID" => session_id,
1398+
}
1399+
1400+
response = @transport.call(delete_env)
1401+
assert_equal 200, response[0]
1402+
1403+
body = JSON.parse(response[2][0])
1404+
assert body["success"]
1405+
end
1406+
13281407
private
13291408

13301409
def create_rack_request(method, path, headers, body = nil)

0 commit comments

Comments
 (0)