Add stateless feature to Streamable HTTP protocol

[bigH]

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]

Does handle_post method need to handle the case for stateless?

[bigH]

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]

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

[bigH]

Happy to.

[bigH]

Rebased on to latest main and squashed my commits.

[bigH]

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

[koic]

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]

@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]

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

[Ginja]

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]

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

[koic]

Can you add user-facing documentation to the README?

[Ginja]

@bigH any chance you have time to revisit this?

[koic]

@bigH ping.

[erickreutz]

We would love to see this merged!

[bigH]

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

[koic]

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