SEP-2575: Make MCP Stateless#2575
Conversation
| 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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Agree it should be added somewhere. I wasn't sure which would get merged first.
There was a problem hiding this comment.
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. :)
43950d9 to
0cc1245
Compare
| export interface RequestMetaObject extends MetaObject { | ||
| progressToken?: ProgressToken; | ||
| + /** | ||
| + * The MCP Protocol Version being used for this request. | ||
| + */ | ||
| + "io.modelcontextprotocol/protocolVersion": string; | ||
| } |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
## Description This PR lays the foundational server-side groundwork for the `>= 2026-06-30` sessionless and stateless feature introduced by [SEP-2575](modelcontextprotocol/modelcontextprotocol#2575) and SEP-2567, tracked in [design/stateless.md](https://github.com/modelcontextprotocol/go-sdk/blob/614460a2253e7772eff6c78f142bfa0428530dc5/design/stateless.md). ### SEP-2575: Stateless MCP * **Per-request protocol detection in `ServerSession.handle()`** Unmarshal `_meta` from the raw JSON-RPC params determines whether each request follows the new protocol. * **Per-request typed accessors on `ServerRequest[P]`** ```go func (r *ServerRequest[P]) ProtocolVersion() string func (r *ServerRequest[P]) ClientInfo() *Implementation func (r *ServerRequest[P]) ClientCapabilities() *ClientCapabilities ``` * **Reject client->server `initialize`, `initialized` and `ping` for new-protocol requests** * **Per-request `_meta` field name constants** Three constants for the wire-protocol field names (`MetaKeyProtocolVersion`, `MetaKeyClientInfo`, `MetaKeyClientCapabilities`) * **Stop synthesizing fake `InitializeParams` for new-protocol requests** Fixes: #966
|
+1 from a multi-client MCP server perspective. We built piia-engram (open-source personal memory layer) and it gets connected by Claude Code, Codex, and Cursor at the same time on the same machine. The init handshake never did anything useful for us — each tool call is already self-contained (user identity comes from config, knowledge IDs are explicit). Having to do a handshake per-client just added startup latency for zero benefit.
One small thing: per-request |
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:
MCP-Protocol-VersionHTTP header and_metafield, with version negotiation throughUnsupportedVersionErrorresponsesserver/discoverRPC — optional discovery endpoint for server capabilities, supported versions, and metadata, replacing the capability exchange from initialization_metaper-request instead of negotiating once at connection timemessages/listenRPC — dedicated endpoint for client-initiated streaming, replacing the existing GET endpoint behavior for Streamable HTTPRelationship 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