Skip to content

Commit 880daa9

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 6f94d64 commit 880daa9

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
@@ -116,6 +116,6 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing
116116

117117
### Integration patterns
118118

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

‎README.md‎

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -357,14 +357,34 @@ transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session
357357
> do not share memory, which breaks session management and SSE connections.
358358
> Stateless mode (`stateless: true`) does not use sessions and works with any server configuration.
359359
360-
#### Rails Controller
360+
#### Rails (mount)
361361

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

366-
You can use `StreamableHTTPTransport#handle_request` to handle requests with proper HTTP
367-
status codes (e.g., 202 Accepted for notifications).
364+
```ruby
365+
# config/routes.rb
366+
server = MCP::Server.new(
367+
name: "my_server",
368+
title: "Example Server Display Name",
369+
version: "1.0.0",
370+
instructions: "Use the tools of this server as a last resort",
371+
tools: [SomeTool, AnotherTool],
372+
prompts: [MyPrompt],
373+
)
374+
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
375+
server.transport = transport
376+
377+
Rails.application.routes.draw do
378+
mount transport => "/mcp"
379+
end
380+
```
381+
382+
#### Rails (controller)
383+
384+
While the mount approach creates a single server at boot time, the controller approach creates a new server per request.
385+
This allows you to customize tools, prompts, or configuration based on the request (e.g., different tools per route).
386+
387+
`StreamableHTTPTransport#handle_request` returns proper HTTP status codes (e.g., 202 Accepted for notifications):
368388

369389
```ruby
370390
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
@@ -33,6 +42,11 @@ def initialize(server, stateless: false, session_idle_timeout: nil)
3342
STREAM_WRITE_ERRORS = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
3443
SESSION_REAP_INTERVAL = 60
3544

45+
# Rack app interface. This transport can be mounted as a Rack app.
46+
def call(env)
47+
handle_request(Rack::Request.new(env))
48+
end
49+
3650
def handle_request(request)
3751
case request.env["REQUEST_METHOD"]
3852
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
@@ -2106,6 +2106,85 @@ class StreamableHTTPTransportTest < ActiveSupport::TestCase
21062106
assert session2_logging.should_notify?("debug")
21072107
end
21082108

2109+
test "call(env) works as a Rack app for POST requests" do
2110+
env = {
2111+
"REQUEST_METHOD" => "POST",
2112+
"PATH_INFO" => "/",
2113+
"rack.input" => StringIO.new({ jsonrpc: "2.0", method: "initialize", id: "init-1" }.to_json),
2114+
"CONTENT_TYPE" => "application/json",
2115+
"HTTP_ACCEPT" => "application/json, text/event-stream",
2116+
}
2117+
2118+
response = @transport.call(env)
2119+
assert_equal 200, response[0]
2120+
assert_equal "application/json", response[1]["Content-Type"]
2121+
2122+
body = JSON.parse(response[2][0])
2123+
assert_equal "2.0", body["jsonrpc"]
2124+
assert_equal "init-1", body["id"]
2125+
end
2126+
2127+
test "call(env) returns 405 for unsupported HTTP methods" do
2128+
env = {
2129+
"REQUEST_METHOD" => "PUT",
2130+
"PATH_INFO" => "/",
2131+
"rack.input" => StringIO.new(""),
2132+
}
2133+
2134+
response = @transport.call(env)
2135+
assert_equal 405, response[0]
2136+
end
2137+
2138+
test "call(env) handles GET SSE stream request" do
2139+
init_env = {
2140+
"REQUEST_METHOD" => "POST",
2141+
"PATH_INFO" => "/",
2142+
"rack.input" => StringIO.new({ jsonrpc: "2.0", method: "initialize", id: "init" }.to_json),
2143+
"CONTENT_TYPE" => "application/json",
2144+
"HTTP_ACCEPT" => "application/json, text/event-stream",
2145+
}
2146+
init_response = @transport.call(init_env)
2147+
session_id = init_response[1]["Mcp-Session-Id"]
2148+
2149+
get_env = {
2150+
"REQUEST_METHOD" => "GET",
2151+
"PATH_INFO" => "/",
2152+
"rack.input" => StringIO.new(""),
2153+
"HTTP_ACCEPT" => "text/event-stream",
2154+
"HTTP_MCP_SESSION_ID" => session_id,
2155+
}
2156+
2157+
response = @transport.call(get_env)
2158+
assert_equal 200, response[0]
2159+
assert_equal "text/event-stream", response[1]["Content-Type"]
2160+
assert response[2].is_a?(Proc)
2161+
end
2162+
2163+
test "call(env) handles DELETE session request" do
2164+
init_env = {
2165+
"REQUEST_METHOD" => "POST",
2166+
"PATH_INFO" => "/",
2167+
"rack.input" => StringIO.new({ jsonrpc: "2.0", method: "initialize", id: "init" }.to_json),
2168+
"CONTENT_TYPE" => "application/json",
2169+
"HTTP_ACCEPT" => "application/json, text/event-stream",
2170+
}
2171+
init_response = @transport.call(init_env)
2172+
session_id = init_response[1]["Mcp-Session-Id"]
2173+
2174+
delete_env = {
2175+
"REQUEST_METHOD" => "DELETE",
2176+
"PATH_INFO" => "/",
2177+
"rack.input" => StringIO.new(""),
2178+
"HTTP_MCP_SESSION_ID" => session_id,
2179+
}
2180+
2181+
response = @transport.call(delete_env)
2182+
assert_equal 200, response[0]
2183+
2184+
body = JSON.parse(response[2][0])
2185+
assert body["success"]
2186+
end
2187+
21092188
private
21102189

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

0 commit comments

Comments
 (0)