Skip to content

SEP-2575: Make MCP Stateless - #2575

Merged
kurtisvg merged 69 commits into
modelcontextprotocol:mainfrom
kurtisvg:sep-1442-reborn
May 11, 2026
Merged

SEP-2575: Make MCP Stateless#2575
kurtisvg merged 69 commits into
modelcontextprotocol:mainfrom
kurtisvg:sep-1442-reborn

Conversation

@kurtisvg

Copy link
Copy Markdown
Contributor

Summary

This PR introduces a SEP for making MCP stateless-by-default, migrated from the original issue discussion at #1442 into the PR-based SEP format per SEP-1850.

Motivation

The current MCP specification requires a mandatory initialization handshake that establishes persistent session state. This creates significant challenges for scalability (load balancing requires sticky sessions), resilience (server failure loses session state), and implementation complexity (both client and server must manage session lifecycles).

What This SEP Proposes

This SEP removes the initialization handshake and replaces it with discrete, stateless alternatives following a "pay as you go" model:

  • Per-request protocol version — via MCP-Protocol-Version HTTP header and _meta field, with version negotiation through UnsupportedVersionError responses
  • server/discover RPC — optional discovery endpoint for server capabilities, supported versions, and metadata, replacing the capability exchange from initialization
  • Per-request client capabilities — clients specify capabilities in _meta per-request instead of negotiating once at connection time
  • messages/listen RPC — dedicated endpoint for client-initiated streaming, replacing the existing GET endpoint behavior for Streamable HTTP

Relationship to Other SEPs

This SEP focuses on removing the initialization handshake and providing stateless alternatives. Session-related concerns are handled separately:

The content of this SEP will be updated in subsequent commits to reflect these decisions and remove session-related material that is now covered by those SEPs.

Fixes #1442

@kurtisvg kurtisvg self-assigned this Apr 14, 2026
@kurtisvg kurtisvg changed the title SEP-XXXX: Make MCP Stateless SEP-2575: Make MCP Stateless Apr 14, 2026
@kurtisvg
kurtisvg requested review from a team as code owners April 14, 2026 21:48
@kurtisvg kurtisvg added SEP transport Related to MCP transports labels Apr 14, 2026
Comment thread docs/seps/2575-stateless-mcp.mdx Outdated
Comment thread docs/seps/2575-stateless-mcp.mdx Outdated
Comment thread docs/seps/2575-stateless-mcp.mdx Outdated
Comment thread docs/seps/2575-stateless-mcp.mdx Outdated
Comment thread docs/seps/2575-stateless-mcp.mdx Outdated
server **MUST** return a `Method not found` JSON-RPC error (`-32601`). For HTTP,
the response status code MUST be `404 Not Found`.

#### `server/discover` RPC

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add the ttl to this that @CaitieM20 is proposing in the other SEP?

One thought on my mind is that for older server/newer client compatibility, realistically the client will actually need to remember the server's older protocol version if it wants to avoid an error on every request trying to figure out the compatible version, so we need a way to cache that.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree it should be added somewhere. I wasn't sure which would get merged first.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, I was going to suggest the exact same thing. I'd prefer to err on the side of putting it in both places, to make sure it doesn't get missed. :)

Comment thread docs/seps/2575-stateless-mcp.mdx Outdated
Comment thread docs/seps/2575-stateless-mcp.mdx Outdated
@dsp-ant dsp-ant added the roadmap/transport Roadmap: Transport Evolution & Scalability (incl. Server Cards) label Apr 15, 2026
Comment thread docs/seps/2575-stateless-mcp.mdx Outdated
@localden localden added the draft SEP proposal with a sponsor. label Apr 15, 2026
Comment thread seps/2575-stateless-mcp.md Outdated
Comment thread seps/2575-stateless-mcp.md Outdated
Comment thread seps/2575-stateless-mcp.md
Comment thread seps/2575-stateless-mcp.md Outdated
Comment thread seps/2575-stateless-mcp.md Outdated
Comment on lines +158 to +164
export interface RequestMetaObject extends MetaObject {
progressToken?: ProgressToken;
+ /**
+ * The MCP Protocol Version being used for this request.
+ */
+ "io.modelcontextprotocol/protocolVersion": string;
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we are overloading _meta here over time. Would we ever add any top level field anymore or shove everything into meta? For me the distinction might be more along the lines of what is a required field by the protocol vs what is an optional field or something provided by an extension. I can't fully point my finger at it, but it feels more right to me, to have a top protocolVersion field instead.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we started with a top-level field, and there was some feedback that we should use _meta instead because of this line in the spec:

Additionally, definitions in the schema may reserve particular names for purpose-specific metadata, as declared in those definitions.

Is protocolVersion the only field you think makes sense at the top level? Or should the others be as well?

Comment thread seps/2575-stateless-mcp.md
Comment thread seps/2575-stateless-mcp.md
Comment thread seps/2575-stateless-mcp.md Outdated
Comment thread seps/2575-stateless-mcp.md Outdated
Comment thread seps/2575-stateless-mcp.md Outdated
Comment thread seps/2575-stateless-mcp.md Outdated
Comment thread seps/2575-stateless-mcp.md Outdated
Comment thread seps/2575-stateless-mcp.md Outdated
koic added a commit to modelcontextprotocol/ruby-sdk that referenced this pull request Aug 13, 2026
## Motivation and Context

Companion to the stateless lifecycle work (SEP-2575, modelcontextprotocol/modelcontextprotocol#2575) for
the 2026-07-28 MCP spec release. The modern lifecycle removed the HTTP GET listening stream;
`subscriptions/listen` replaces it as a long-lived POST that opts in to server change notifications.
The Python SDK ships the server side of this as its SEP-2575 event-bus work (python-sdk PR /modelcontextprotocol/python-sdk#3035);
the TypeScript SDK landed it in PR modelcontextprotocol/typescript-sdk#2321.

Wire behavior, per the draft schema:

- The request carries a REQUIRED `notifications` filter (`SubscriptionFilter`): `toolsListChanged`,
  `promptsListChanged`, `resourcesListChanged`, and `resourceSubscriptions` (URI list, replacing
  the legacy `resources/subscribe` RPC). Every type is opt-in; the server MUST NOT send types
  the client did not request.
- The first stream message is `notifications/subscriptions/acknowledged`, reporting the subset of
  requested types the server agreed to honor. Honoring reads the capability FLAGS that promise delivery
  (`listChanged`, `subscribe`), the same derivation `server/discover` uses for its era-aware capability stripping;
  the mere presence of a primitive's capability is not enough.
- Every notification delivered on the stream carries the correlating `io.modelcontextprotocol/subscriptionId`
  (the listen request id) in `_meta`.
- A graceful teardown (transport `close`) sends a `SubscriptionsListenResult` response before closing the stream,
  stamped with the REQUIRED 2026-07-28 `resultType` at its construction site (it never passes through the dispatch path);
  an abrupt disconnect sends nothing.

Implementation:

- `StreamableHTTPTransport` intercepts `subscriptions/listen` on the modern path (after header and envelope validation)
  and serves it as a long-lived SSE stream, using the same register-and-return body proc pattern as the legacy GET stream.
  Subscriptions live in an in-process registry keyed by the listen request id; fan-out hooks into `send_notification` ahead of
  the legacy delivery, so a resource updated by one session's tool call also reaches modern subscribers.
  The matching snapshot is taken under the transport mutex, but stream writes happen outside it,
  matching the legacy delivery paths: a slow or stalled subscriber must not block the transport.
  Duplicate subscription ids close the new stream instead of double-registering.
- Concurrent listen streams are capped (`max_listen_subscriptions:`, default 1000, `nil` to opt out);
  a listen request past the cap is rejected with HTTP 503, like the `max_sessions` guard against session floods.
  Each stream holds an open connection for its lifetime, so without a bound an unauthenticated client can retain
  unbounded connections.
- Each stream is kept alive by an SSE comment frame written every `listen_keepalive_interval:` seconds
  (default 15, matching the TypeScript SDK; `nil` to opt out when an upstream proxy pings the stream).
  A silently dropped connection would otherwise hold its capped slot until the next fan-out write failed,
  so on a quiet server the cap would ratchet down permanently; the periodic write detects the dead peer
  and frees the slot. A comment frame cannot corrupt an interleaved notification's JSON, and the write
  happens outside the transport mutex, reusing the legacy GET stream's keepalive mechanism.
- Every SSE response now carries `x-accel-buffering: no`, which the spec asks of SSE streams and both
  reference SDKs send: a buffering reverse proxy would hold events back instead of delivering them as
  they are written, and on a listen stream it would also swallow the keepalive frames a dropped peer
  is detected by. The header rides the shared `SSE_HEADERS`, so the legacy streams gain it too.
- stdio does not serve the stream, matching the Python SDK's stream-pair behavior: no server handler is registered,
  so the method answers `-32601`.
- `Server#discover` becomes era-aware about notification delivery: `listChanged`/`subscribe` capability flags
  promise delivery over `subscriptions/listen` streams in the modern lifecycle, so they are stripped when
  the transport does not serve that RPC (the new `Transport#serves_subscriptions_listen?` seam, true for `StreamableHTTPTransport`).
- The conformance fixture defines the diagnostic triggers the `server-stateless` scenario calls
  (`test_trigger_tool_change` / `test_trigger_prompt_change`): each broadcasts its list-changed notification
  to the listen streams and returns, mirroring the suite's TypeScript reference fixture, which mutates nothing either.

Out of scope, noted for follow-ups: an external event bus for multi-worker deployments, and the client-side listen driver
(the Python reference is python-sdk PR modelcontextprotocol/python-sdk#3047).

Refs #389.

## How Has This Been Tested?

New tests in `test/mcp/server/transports/streamable_http_transport_test.rb` cover:
the SSE response with the acknowledgement as the first event (including the honored-subset reduction for unsupported types and
for capability entries lacking the delivery flag), the `notifications` filter and envelope requirements (400 responses),
opt-in-only delivery with the correlating `subscriptionId`, URI-scoped `resources/updated` delivery, per-subscription ids across
concurrent streams, the graceful close result carrying `resultType: "complete"`, duplicate-id rejection, the 503 past
the concurrent stream cap, the keepalive (writing the comment frame outside the mutex, freeing a dead peer's slot,
no thread when the interval is `nil`, and the positive-or-nil interval validation), and `x-accel-buffering: no`
on both the listen stream and the legacy GET stream.
`test/mcp/server/transports/stdio_transport_test.rb` asserts `-32601` over stdio,
and `test/mcp/server_test.rb` covers the era-aware capability stripping in `server/discover` for both transport kinds.

`bundle exec rake` (tests, RuboCop, and conformance baseline) passes.

Against the conformance fixture server at `--spec-version 2026-07-28`, the `server-stateless` subscription checks
all report SUCCESS: the acknowledgement, `subscriptionId` tagging, and filter-containment MUSTs, plus both
list-changed SHOULD checks driven by the new trigger tools. The `--requirements 2025-11-25` server leg
passes 78/78, unchanged.

## Breaking Changes

None. The method was previously unhandled (`-32601` everywhere); the only observable change to existing responses is that
`server/discover` no longer advertises `listChanged`/`subscribe` flags on transports that cannot deliver those notifications in
the modern lifecycle, which `server/discover` has not shipped in a gem release with anyway.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation final SEP finalized. roadmap/transport Roadmap: Transport Evolution & Scalability (incl. Server Cards) SEP transport Related to MCP transports

Projects

Status: Review Batch

Development

Successfully merging this pull request may close these issues.

SEP-1442: Make MCP Stateless (by default)