Add `stateless` feature to Streamable HTTP protocol by bigH · Pull Request #101 · modelcontextprotocol/ruby-sdk

bigH · 2025-07-31T17:57:46Z

See: #99

Currently, this implementation of MCP requires that sessions are held in memory for Server-Sent Events (SSEs). The session data maps an ID to a live IO stream. This doesn't work for Chime for a few reasons:

We run >1 replica, so in-memory storage of session state is not going to work
When contacting a backend with no knowledge of a given session, the server responds with an error, breaking downstream agent functionality
Chime's default configuration doesn't allow for long-lived connections and connections are terminated forcibly after a timeout

So, here we add tests and validate that stateless configuration behaves according to spec. In situations where the spec is unclear about something, we defer to the Python SDK.

koic · 2025-08-01T15:31:04Z

Does handle_post method need to handle the case for stateless?

bigH · 2025-08-01T22:21:10Z

Does handle_post method need to handle the case for stateless?

My understanding is that it does not. handle_post calls handle_regular_request, which only uses SSE if a stream exists.

I've tested this against my own service and it works properly. What would it take to get this merged?

koic · 2025-08-02T10:41:31Z

Ah, I see. Thank you for the explanation. Can you squash your commits into one?

bigH · 2025-08-05T17:28:07Z

Happy to.

bigH · 2025-08-05T17:32:21Z

Rebased on to latest main and squashed my commits.

bigH · 2025-08-06T17:17:47Z

Bump @koic. I think this is good to review/merge.

test/mcp/server/transports/streamable_http_transport_test.rb

koic · 2025-08-19T02:42:38Z

test/mcp/server/transports/streamable_http_transport_test.rb

+
+          response = stateless_transport.handle_request(request)
+          assert_equal 202, response[0]
+          assert_equal({ "Content-Type" => "application/json" }, response[1])


It seems that this assertion is failing due to the changes in #105. Can you rebase with the latest main branch and update this assertion as follows?

Suggested change

assert_equal({ "Content-Type" => "application/json" }, response[1])

assert_empty(response[1])

koic · 2025-08-20T17:31:04Z

@bigH This looks good overall to me. Can you rebase on the latest main branch, make sure the tests pass, and squash the commits into a single one?

Ginja · 2025-08-21T05:15:37Z

I tested this change on an internal MCP server and it looks good 👍

Ginja · 2025-08-21T22:24:35Z

On further testing I may have found a bug with this feature, but only when specifically using socketry/falcon (vs Puma).

{
    "time": "2025-08-21T20:28:04+00:00",
    "severity": "error",
    "pid": 20,
    "oid": 1176,
    "fiber_id": 1192,
    "subject": "Protocol::Rack::Adapter::Rack31",
    "annotation": "Reading HTTP/1.1 requests for Async::HTTP::Protocol::HTTP1::Server.",
    "message": "undefined method 'bytesize' for nil",
    "event": {
        "type": "failure",
        "root": "/app",
        "class": "NoMethodError",
        "message": "undefined method 'bytesize' for nil",
        "backtrace": [
            "/artifacts/bundle/ruby/3.4.0/gems/protocol-rack-0.16.0/lib/protocol/rack/body/enumerable.rb:27:in 'Array#sum'",
            "/artifacts/bundle/ruby/3.4.0/gems/protocol-rack-0.16.0/lib/protocol/rack/body/enumerable.rb:27:in 'Protocol::Rack::Body::Enumerable.wrap'",
            "/artifacts/bundle/ruby/3.4.0/gems/protocol-rack-0.16.0/lib/protocol/rack/body.rb:64:in 'Protocol::Rack::Body.wrap'",
            "/artifacts/bundle/ruby/3.4.0/gems/protocol-rack-0.16.0/lib/protocol/rack/response.rb:53:in 'Protocol::Rack::Response.wrap'",
            "/artifacts/bundle/ruby/3.4.0/gems/protocol-rack-0.16.0/lib/protocol/rack/adapter/generic.rb:160:in 'Protocol::Rack::Adapter::Generic#call'",
            "/artifacts/bundle/ruby/3.4.0/gems/protocol-http-0.52.0/lib/protocol/http/middleware.rb:53:in 'Protocol::HTTP::Middleware#call'",
            "/artifacts/bundle/ruby/3.4.0/gems/protocol-http-0.52.0/lib/protocol/http/content_encoding.rb:40:in 'Protocol::HTTP::ContentEncoding#call'",
            "/artifacts/bundle/ruby/3.4.0/gems/protocol-http-0.52.0/lib/protocol/http/middleware.rb:53:in 'Protocol::HTTP::Middleware#call'",
            "/artifacts/bundle/ruby/3.4.0/gems/falcon-0.52.3/lib/falcon/server.rb:66:in 'Falcon::Server#call'",
            "/artifacts/bundle/ruby/3.4.0/gems/async-http-0.91.0/lib/async/http/server.rb:57:in 'block in Async::HTTP::Server#accept'",
            "/artifacts/bundle/ruby/3.4.0/gems/async-http-0.91.0/lib/async/http/protocol/http1/server.rb:72:in 'Async::HTTP::Protocol::HTTP1::Server#each'",
            "/artifacts/bundle/ruby/3.4.0/gems/async-http-0.91.0/lib/async/http/server.rb:49:in 'Async::HTTP::Server#accept'",
            "/artifacts/bundle/ruby/3.4.0/gems/falcon-0.52.3/lib/falcon/server.rb:57:in 'Falcon::Server#accept'",
            "/artifacts/bundle/ruby/3.4.0/gems/io-endpoint-0.15.2/lib/io/endpoint/wrapper.rb:216:in 'block (2 levels) in IO::Endpoint::Wrapper#accept'",
            "/artifacts/bundle/ruby/3.4.0/gems/async-2.27.4/lib/async/task.rb:183:in 'block in Async::Task#run'",
            "/artifacts/bundle/ruby/3.4.0/gems/async-2.27.4/lib/async/task.rb:427:in 'block in Async::Task#schedule'"
        ]
    }
}

Digging into it, it looks like nil is not a valid response with Falcon. Adding the following to streamable_http_transport.rb fixes the issue. Something we may want to consider for those using Falcon.

        def handle_regular_request(body_string, session_id)
          unless @stateless
            # If session ID is provided, but not in the sessions hash, return an error
            if session_id && !@sessions.key?(session_id)
              return [400, { "Content-Type" => "application/json" }, [{ error: "Invalid session ID" }.to_json]]
            end
          end

          # Ensure we always have a valid response body - convert nil to empty string
          response = @server.handle_json(body_string) || ""

bigH · 2025-08-23T04:42:29Z

I'll come back to this next week and handle what you shared @Ginja @koic

koic · 2025-08-24T17:34:13Z

Can you add user-facing documentation to the README?

Ginja · 2025-10-06T05:08:00Z

@bigH any chance you have time to revisit this?

koic · 2025-10-20T04:02:37Z

@bigH ping.

erickreutz · 2025-10-23T12:50:36Z

We would love to see this merged!

bigH · 2025-10-24T18:08:28Z

I'm pretty busy, but will take a look at finalizing this during the weekend.

koic · 2025-10-30T00:14:36Z

@bigH Can you add documentation for this feature to the README.md and finally squash commits into one?

- Create failing tests for `stateless` mode - Implement `stateless` mode by turning of SSE in Streamable HTTP, making the interaction a standard HTTP Req/Resp

bigH · 2025-11-04T23:26:44Z

@Ginja @koic applied both your suggestions, added docs and rebased. Everything seems to be passing.

koic

The overall foundation looks good. Thank you for working on this. There are a few parts of the documentation that might benefit from refinement, but those can be addressed separately later.

`stateless` was supported in #101. However, as shown in the official specification below, the supported transports are stdout and Streamable HTTP, and whether it is stateless is a detail specific to Streamable HTTP: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports This PR updates the documentation to describe `stateless` as part of the Streamable HTTP section.

bigH force-pushed the stateless branch 2 times, most recently from a2c47d2 to ca3537e Compare August 5, 2025 17:32

koic previously approved these changes Aug 6, 2025

View reviewed changes

bigH dismissed koic’s stale review via e953733 August 6, 2025 04:34

bigH force-pushed the stateless branch 2 times, most recently from 89dcd20 to 0ecdd98 Compare August 6, 2025 05:51

koic reviewed Aug 9, 2025

View reviewed changes

test/mcp/server/transports/streamable_http_transport_test.rb Outdated Show resolved Hide resolved

koic reviewed Aug 9, 2025

View reviewed changes

test/mcp/server/transports/streamable_http_transport_test.rb Outdated Show resolved Hide resolved

koic reviewed Aug 19, 2025

View reviewed changes

koic linked an issue Oct 24, 2025 that may be closed by this pull request

Stateless MCP Servers #99

Closed

bigH force-pushed the stateless branch from 591dbd3 to 87ee55f Compare October 28, 2025 15:26

Introduce stateless mode to allow for HA

08a84c7

- Create failing tests for `stateless` mode - Implement `stateless` mode by turning of SSE in Streamable HTTP, making the interaction a standard HTTP Req/Resp

bigH force-pushed the stateless branch from b597de0 to 08a84c7 Compare November 4, 2025 23:26

bigH marked this pull request as draft November 4, 2025 23:27

bigH marked this pull request as ready for review November 4, 2025 23:27

koic approved these changes Nov 6, 2025

View reviewed changes

koic merged commit 400a56e into modelcontextprotocol:main Nov 7, 2025
5 checks passed

koic mentioned this pull request Nov 8, 2025

[Doc] Tweak the README for stateless #176

Merged

9 tasks

	assert_equal({ "Content-Type" => "application/json" }, response[1])
	assert_empty(response[1])

Conversation

bigH commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

koic commented Aug 1, 2025

Uh oh!

bigH commented Aug 1, 2025

Uh oh!

koic commented Aug 2, 2025

Uh oh!

bigH commented Aug 5, 2025

Uh oh!

bigH commented Aug 5, 2025

Uh oh!

bigH commented Aug 6, 2025

Uh oh!

Uh oh!

Uh oh!

koic Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

koic commented Aug 20, 2025

Uh oh!

Ginja commented Aug 21, 2025

Uh oh!

Ginja commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bigH commented Aug 23, 2025

Uh oh!

koic commented Aug 24, 2025

Uh oh!

Ginja commented Oct 6, 2025

Uh oh!

koic commented Oct 20, 2025

Uh oh!

erickreutz commented Oct 23, 2025

Uh oh!

bigH commented Oct 24, 2025

Uh oh!

koic commented Oct 30, 2025

Uh oh!

bigH commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

koic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bigH commented Jul 31, 2025 •

edited

Loading

Ginja commented Aug 21, 2025 •

edited

Loading

bigH commented Nov 4, 2025 •

edited

Loading