Add MCP Streamable HTTP specification support for the client #210

keisku · 2026-01-09T14:22:43Z

Motivation and Context

Implements the MCP Streamable HTTP specification for the Ruby SDK client.

Already supported:

POST with JSON body
Accept: application/json, text/event-stream header
Parse application/json response

This PR adds:

Parse text/event-stream (SSE) response
Session management (MCP-Session-Id header)
Handle 404 as session expiration
DELETE for session termination
Protocol version header (MCP-Protocol-Version)

How Has This Been Tested?

Terminal 1 - Server

bundle exec ruby ./examples/streamable_http_server.rb

# After client requests...

[MCP] Request: initialize (id: 7bb764c8-cd31-4ca8-8073-a7fc977a53dd)
[SSE] INFO 23:03:05.053 - New client initializing session
[MCP] Response: success (id: 7bb764c8-cd31-4ca8-8073-a7fc977a53dd)
[SSE] INFO 23:03:05.053 - Session created: 6e58438d-ca95-47d3-b2cd-4df7c6915dcf
::1 - - [09/Jan/2026:23:03:05 +0900] "POST / HTTP/1.1" 200 - 0.0003
[MCP] Request: tools/list (id: d2cc3984-cbf4-4e31-9513-074b36c7dab5)
[MCP] Response: success (id: d2cc3984-cbf4-4e31-9513-074b36c7dab5)
::1 - - [09/Jan/2026:23:03:05 +0900] "POST / HTTP/1.1" 200 - 0.0001
[SSE] INFO 23:03:05.055 - SSE connection request for session: 6e58438d-ca95-47d3-b2cd-4df7c6915dcf
[SSE] INFO 23:03:05.055 - SSE stream established
::1 - - [09/Jan/2026:23:03:05 +0900] "GET / HTTP/1.1" 200 - 0.0001
[MCP] Request: tools/call (id: 822967ca-da23-484f-86b3-caaef42e4209)
[SSE] INFO 23:03:17.068 - Returning notification message: HELLO
[SSE] INFO 23:03:17.068 - Response sent via SSE stream
::1 - - [09/Jan/2026:23:03:17 +0900] "POST / HTTP/1.1" 200 - 3.0057
[MCP] Request: tools/call (id: fa2ad1e5-1fef-4d02-b20e-3f1ae9425bd0)
[SSE] INFO 23:03:24.339 - Response sent via SSE stream
::1 - - [09/Jan/2026:23:03:24 +0900] "POST / HTTP/1.1" 200 - 0.0005
[MCP] Request: tools/list (id: 6d532649-b594-4f7f-bfce-ebb091015e6b)
[SSE] INFO 23:03:26.380 - Response sent via SSE stream
::1 - - [09/Jan/2026:23:03:26 +0900] "POST / HTTP/1.1" 200 - 0.0002
::1 - - [09/Jan/2026:23:03:27 +0900] "DELETE / HTTP/1.1" 200 - 0.0001

Terminal 2 - Client

bundle exec ruby examples/streamable_http_client.rb
MCP Streamable HTTP Client (SDK + SSE)
Make sure the server is running (ruby examples/streamable_http_server.rb)
============================================================
=== Initializing session ===
Session ID: 6e58438d-ca95-47d3-b2cd-4df7c6915dcf
Protocol Version: 2025-11-25
Server Info: {"icons" => [], "name" => "sse_test_server", "version" => "0.1.0"}
=== Listing tools ===
  - notification_tool: Returns a notification message that will be sent via SSE if stream is active
  - echo: Simple echo tool
[CLIENT] INFO 23:03:05.054 - Connecting to SSE stream...
[CLIENT] INFO 23:03:05.055 - SSE stream connected successfully

=== Available Actions ===
1. Send notification (triggers SSE event)
2. Echo message
3. List tools
0. Exit

Choose an action:
1
Enter notification message: HELLO
Enter delay in seconds (0 for immediate): 3
=== Calling tool: notification_tool ===
[CLIENT] INFO 23:03:17.068 - SSE event: {"jsonrpc":"2.0","id":"822967ca-da23-484f-86b3-caaef42e4209","result":{"content":[{"type":"text","text":"Notification: HELLO (timestamp: 2026-01-09T23:03:17+09:00)"}],"isError":false}}
Response: {
  "accepted": true
}

=== Available Actions ===
1. Send notification (triggers SSE event)
2. Echo message
3. List tools
0. Exit

Choose an action:
2
Enter message to echo: HELOOOOOOO
=== Calling tool: echo ===
[CLIENT] INFO 23:03:24.339 - SSE event: {"jsonrpc":"2.0","id":"fa2ad1e5-1fef-4d02-b20e-3f1ae9425bd0","result":{"content":[{"type":"text","text":"Echo: HELOOOOOOO"}],"isError":false}}
Response: {
  "accepted": true
}

=== Available Actions ===
1. Send notification (triggers SSE event)
2. Echo message
3. List tools
0. Exit

Choose an action:
3
=== Listing tools ===
(Note: Response will appear in SSE stream when active)
[CLIENT] INFO 23:03:26.380 - SSE event: {"jsonrpc":"2.0","id":"6d532649-b594-4f7f-bfce-ebb091015e6b","result":{"tools":[{"name":"notification_tool","description":"Returns a notification message that will be sent via SSE if stream is active","inputSchema":{"properties":{"message":{"type":"string","description":"Message to send via SSE"},"delay":{"type":"number","description":"Delay in seconds before returning (optional)"}},"required":["message"],"type":"object"}},{"name":"echo","description":"Simple echo tool","icons":[],"inputSchema":{"properties":{"message":{"type":"string"}},"required":["message"],"type":"object"}}]}}

=== Available Actions ===
1. Send notification (triggers SSE event)
2. Echo message
3. List tools
0. Exit

Choose an action:
0
[CLIENT] INFO 23:03:27.995 - Exiting...
=== Closing session ===
Session closed

Breaking Changes

None. The public send_request(request:) method signature is preserved for backward compatibility.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

API Design

MCP::Client::HTTP#send_request(request:) - Returns body only (backward compatible)
MCP::Client::HTTP#post(body:, headers:) - Returns Response struct with body + headers (for session management)
MCP::Client::HTTP#delete(headers:) - For session termination
MCP::Client#connect(client_info:, protocol_version:, capabilities:) - Initialization handshake
MCP::Client#close - Session termination

Pending TODOs

atesgoral · 2026-01-10T00:06:20Z

examples/streamable_http_client.rb

      if response.code == "200"
        logger.info("SSE stream connected successfully")

        response.read_body do |chunk|


Let's use https://rubygems.org/gems/event_stream_parser for parsing. SSE appears easy to parse but it has weird edge cases.

Thanks for kicking off the effort! I've been planning on porting this standalone client I had written for a project, but never got around to doing it: https://gist.github.com/atesgoral/75172912b5951d9be33497b80aba4397

You can see how event_stream_parser can be used for parsing chunks as they come in.

… spec

keisku · 2026-01-15T01:23:52Z

@atesgoral Thanks for reviewing this! I've addressed it.

keisku · 2026-01-26T04:51:29Z

@atesgoral Any chance you could take a look at this PR?

koic · 2026-01-26T08:26:49Z

examples/streamable_http_client.rb

  Net::HTTP.start(uri.host, uri.port) do |http|
    request = Net::HTTP::Get.new(uri)
-    request["Mcp-Session-Id"] = session_id
+    request["MCP-Session-Id"] = session_id


This change doesn't appear to be intentional.

koic · 2026-01-26T08:28:11Z

examples/streamable_http_client.rb

+  logger = create_logger
+
+  puts <<~MESSAGE
+    MCP Streamable HTTP Client (SDK + SSE)


The mention of the "SDK" seems redundant.

koic · 2026-01-26T08:30:21Z

examples/streamable_http_client.rb

+    puts "Session ID: #{client.session_id}"
+    puts "Protocol Version: #{client.protocol_version}"
+    puts "Server Info: #{init_response.dig("result", "serverInfo")}"


Suggested change

puts "Session ID: #{client.session_id}"

puts "Protocol Version: #{client.protocol_version}"

puts "Server Info: #{init_response.dig("result", "serverInfo")}"

puts <<~MESSAGE

Session ID: #{client.session_id}

Protocol Version: #{client.protocol_version}

Server Info: #{init_response.dig("result", "serverInfo")}

MESSAGE

koic · 2026-01-26T08:31:40Z

examples/streamable_http_client.rb

+        Choose an action:#{" "}
+      MENU
+
+      choice = gets&.chomp


The safe navigation operator doesn't seem necessary. Is there any case where this could be nil?

Suggested change

choice = gets&.chomp

choice = gets.chomp

Can you look over the other similar parts as well?

koic · 2026-01-26T08:36:10Z

examples/streamable_http_client.rb

+    logger.error(e.backtrace.first(5).join("\n"))
+  ensure
+    # Clean up SSE thread
+    sse_thread&.kill if sse_thread&.alive?


At least if sse_thread is alive, the receiver of kill should exist. Is safe navigation necessary in each case?

koic · 2026-01-26T08:39:23Z

lib/mcp/client.rb

  class Client
+    # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http
+    LATEST_PROTOCOL_VERSION = "2025-11-25"
+    SESSION_ID_HEADER = "MCP-Session-Id"


It may be better to make the notation consistent.

Suggested change

SESSION_ID_HEADER = "MCP-Session-Id"

SESSION_ID_HEADER = "Mcp-Session-Id"

koic · 2026-01-26T08:41:29Z

lib/mcp/server/transports/streamable_http_transport.rb

 module MCP
  class Server
    module Transports
+      # TODO: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#resumability-and-redelivery


It would be helpful to describe what is expected to be done in this TODO.

koic · 2026-01-26T08:41:34Z

lib/mcp/server/transports/streamable_http_transport.rb

        REQUIRED_GET_ACCEPT_TYPES = ["text/event-stream"].freeze

        def handle_request(request)
+          # TODO: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#security-warning


Add MCP Streamable HTTP specification support for the client

09637b6

atesgoral reviewed Jan 10, 2026

View reviewed changes

scutuatua-crypto approved these changes Jan 10, 2026

View reviewed changes

keisku added 3 commits January 13, 2026 09:09

use event_stream_parser

4765528

Simplify Client#close since HTTP#delete handles errors internally

bd55244

Clarify that the SDK lacks HTTP GET support for SSE streaming per MCP…

03a76cd

… spec

keisku requested a review from atesgoral January 13, 2026 00:52

koic reviewed Jan 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add MCP Streamable HTTP specification support for the client #210

Add MCP Streamable HTTP specification support for the client #210

Uh oh!

keisku commented Jan 9, 2026

Uh oh!

atesgoral Jan 10, 2026 •

edited

Loading

Uh oh!

keisku commented Jan 15, 2026

Uh oh!

keisku commented Jan 26, 2026

Uh oh!

koic Jan 26, 2026

Uh oh!

koic Jan 26, 2026

Uh oh!

koic Jan 26, 2026

Uh oh!

koic Jan 26, 2026

Uh oh!

koic Jan 26, 2026

Uh oh!

koic Jan 26, 2026

Uh oh!

koic Jan 26, 2026

Uh oh!

koic Jan 26, 2026

Uh oh!

koic Jan 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	SESSION_ID_HEADER = "MCP-Session-Id"
	SESSION_ID_HEADER = "Mcp-Session-Id"

Add MCP Streamable HTTP specification support for the client #210

Are you sure you want to change the base?

Add MCP Streamable HTTP specification support for the client #210

Uh oh!

Conversation

keisku commented Jan 9, 2026

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

API Design

Pending TODOs

Uh oh!

atesgoral Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

keisku commented Jan 15, 2026

Uh oh!

keisku commented Jan 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

atesgoral Jan 10, 2026 •

edited

Loading