Skip to content

Commit 11f3534

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 2a1c9b7 commit 11f3534

File tree

6 files changed

+235
-106
lines changed

6 files changed

+235
-106
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
@@ -103,14 +103,34 @@ $ ruby examples/stdio_server.rb
103103
{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"example_tool","arguments":{"message":"Hello"}}}
104104
```
105105

106-
#### Rails Controller
106+
#### Rails (mount)
107107

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

112-
You can use `StreamableHTTPTransport#handle_request` to handle requests with proper HTTP
113-
status codes (e.g., 202 Accepted for notifications).
110+
```ruby
111+
# config/routes.rb
112+
server = MCP::Server.new(
113+
name: "my_server",
114+
title: "Example Server Display Name",
115+
version: "1.0.0",
116+
instructions: "Use the tools of this server as a last resort",
117+
tools: [SomeTool, AnotherTool],
118+
prompts: [MyPrompt],
119+
)
120+
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
121+
server.transport = transport
122+
123+
Rails.application.routes.draw do
124+
mount transport => "/mcp"
125+
end
126+
```
127+
128+
#### Rails (controller)
129+
130+
While the mount approach creates a single server at boot time, the controller approach creates a new server per request.
131+
This allows you to customize tools, prompts, or configuration based on the request (e.g., different tools per route).
132+
133+
`StreamableHTTPTransport#handle_request` returns proper HTTP status codes (e.g., 202 Accepted for notifications):
114134

115135
```ruby
116136
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: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,15 @@
33
require "json"
44
require_relative "../../transport"
55

6+
# This file is autoloaded only when `StreamableHTTPTransport` is referenced,
7+
# so the `rack` dependency does not affect `StdioTransport` users.
8+
begin
9+
require "rack"
10+
rescue LoadError
11+
raise LoadError, "The 'rack' gem is required to use the StreamableHTTPTransport. " \
12+
"Add it to your Gemfile: gem 'rack'"
13+
end
14+
615
module MCP
716
class Server
817
module Transports
@@ -39,6 +48,11 @@ def initialize(server, stateless: false, session_idle_timeout: nil)
3948
STREAM_WRITE_ERRORS = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
4049
SESSION_REAP_INTERVAL = 60
4150

51+
# Rack app interface. This transport can be mounted as a Rack app.
52+
def call(env)
53+
handle_request(Rack::Request.new(env))
54+
end
55+
4256
def handle_request(request)
4357
case request.env["REQUEST_METHOD"]
4458
when "POST"
@@ -531,7 +545,7 @@ def handle_request_with_sse_response(body_string, session_id, server_session, re
531545
end
532546
end
533547

534-
[200, SSE_HEADERS, body]
548+
[200, SSE_HEADERS.dup, body]
535549
end
536550

537551
# Returns the SSE stream available for server-to-client messages.
@@ -613,7 +627,7 @@ def session_already_connected_response
613627
def setup_sse_stream(session_id)
614628
body = create_sse_body(session_id)
615629

616-
[200, SSE_HEADERS, body]
630+
[200, SSE_HEADERS.dup, body]
617631
end
618632

619633
def create_sse_body(session_id)

0 commit comments

Comments
 (0)