René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"SEP-1335: Address Streamable HTTP transport issues","articleBody":"**Authors:** Jonathan Hefner (@jonathanhefner)\n**Status:** Draft\n**Type:** Standards Track\n**Created:** 2025-08-12\n\n## Abstract\n\nThis SEP proposes changes to the Streamable HTTP transport in order to mitigate issues regarding resumability and long-running connections.\n\n\n## Motivation\n\nThe Streamable HTTP transport currently exhibits the following issues:\n\n- **Unable to resume without an initial SSE event**\n\n  If a server starts an SSE stream but a disconnection occurs before an event is sent, there is no way for the client to resume the stream, because resuming requires a `Last-Event-ID`.\n\n  This is especially problematic because the spec says that [disconnection should not be interpreted as the client cancelling its request](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/eba3959164c6b1ef87b87c8fe3574972f3f30055/docs/specification/draft/basic/transports.mdx?plain=1#L116).\n\n- **Servers must maintain potentially long-running connections**\n\n  The spec [does not allow](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/eba3959164c6b1ef87b87c8fe3574972f3f30055/docs/specification/draft/basic/transports.mdx?plain=1#L109-L111) servers to close a connection while computing a result.  In other words, barring client-side disconnection, servers must maintain potentially long-running connections.\n\n- **Clients may reconnect excessively**\n\n  There is no indication of how long clients should wait before attempting reconnection.  If servers were allowed to disconnect at will, there is no established scheme to prevent clients from reconnecting immediately.\n\n- TODO: elaborate on challenges for load-balanced servers concerning server-to-client requests\n\n\n## Proposed Changes\n\n### `rel=\"stream\"` URL\n\nWhen a server starts an SSE stream, it MAY send an HTTP `Link` header that includes a `rel=\"stream\"` URL.  The server MAY embed whatever values it chooses in the URL, such as a unique request ID; however, the URL MUST be same-origin (same scheme, hostname, and port) as the server URL.\n\nIn the event of a disconnection, the client SHOULD resume the SSE stream.  To resume the stream the client MUST send a GET request to the `rel=\"stream\"` URL instead of the typical `/mcp` endpoint.\n\nWhen sending a GET request to the `rel=\"stream\"` URL, the client SHOULD include an appropriate `Last-Event-ID` header (if possible), and the server MUST respect the `Last-Event-ID` header.\n\n#### Rationale\n\nThe `rel=\"stream\"` URL acts as a unique endpoint for clients to resume the stream, regardless of having received an initial event.  It can also provide benefits with respect to routing.\n\nAn alternative would be to (automatically, transparently) send an empty initial SSE event with an event ID to prime the client to reconnect.  However, the client will likely receive an HTTP header before it receives the first SSE event, reducing the window in which a network failure could prevent the client from receiving resumption information.\n\nNote that neither approach fully eliminates that window of failure.  To fully eliminate the window of failure, we should introduce a mechanism like idempotency tokens.  However, that may impose a slightly higher burden on the server, may be relevant to other transports, and is outside the scope of this SEP.\n\n#### Backward Compatibility\n\n- **New Client + Old Server**: Server will not send header.  No backward incompatibility as long as client supports the old way of resuming (GET `/mcp`).\n- **Old Client + New Server**: Client will ignore header.  No backward incompatibility as long as server supports the old way of resuming (GET `/mcp`).\n\n### Allow server to disconnect at will\n\nChange [this part of the spec](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/04c6e1f0ea6544c7df307fb2d7c637efe34f58d3/docs/specification/draft/basic/transports.mdx?plain=1#L109-L111):\n\n\u003e The server **SHOULD NOT** close the SSE stream before sending the JSON-RPC _response_ for the received JSON-RPC _request_\n\nTo say:\n\n\u003e The server **MAY** close the connection before sending the JSON-RPC _response_ if it has sent a `Link` header with a `rel=\"stream\"` URL.\n\nFurthermore, if the server does close the connection before sending the JSON-RPC response, at some point before closing the connection, the server SHOULD send the [`retry` field](https://html.spec.whatwg.org/multipage/server-sent-events.html#:~:text=field%20name%20is%20%22retry%22) in the stream.\n\nThe client SHOULD respect the `retry` field when resuming the stream.\n\n#### Rationale\n\nServers may disconnect at will, avoiding long-running connections.  Sending a `retry` field should prevent the client from hammering the server with inappropriate reconnection attempts.\n\n#### Backward Compatibility\n\n- **New Client + Old Server**: No backward incompatibility.\n- **Old Client + New Server**: Client should interpret an at-will disconnect the same as a network failure.  `retry` field is part of the SSE standard.  No backward incompatibility if client already implements proper SSE resuming logic.\n\n### Multi-turn requests for server-to-client requests\n\nWhen the server requires additional input from the client, it should send server-to-client requests (e.g., sampling requests) on the SSE stream.  When the server wants to wait for input from the client, it MUST disconnect.  The next time the client attempts to reconnect via the `rel=\"stream\"` URL, the server MUST respond with HTTP status code `204 No Content` (which is the standard mechanism to signal the end of an SSE stream).\n\nWhen the client receives a request from the server over the SSE stream, it should process the request, but it MUST store its response in a buffer instead of sending it to the server.  Once the SSE processing loop has been terminated due to the `204 No Content` response, the client MUST POST its buffered responses (as a JSON array) to the `rel=\"stream\"` URL.\n\nThen, the server MUST respond with a new SSE stream, including a `Link` header with a `rel=\"stream\"` URL.\n\nThis multi-turn interaction should repeat until the client has received the response to its original request.\n\n**Server algorithm:**\n\n1. Server sends messages, including server-to-client requests, until it wants to wait for input from the client.\n2. Server disconnects.\n3. When client GETs `rel=\"stream\"` URL, server responds with `204 No Content`.\n4. When client POSTs input to `rel=\"stream\"` URL, server returns new SSE stream, including new `rel=\"stream\"` URL.\n5. Go to step 1.\n\n**Client algorithm:**\n\n1. Client processes SSE stream events.  If an event is a server-to-client request, client stores its response in a buffer.\n2. When server disconnects, client attempts to reconnect but receives `204 No Content`, signaling end of the SSE stream.\n3. If there are buffered responses to server-to-client requests, client POSTs responses to `rel=\"stream\"` URL.\n4. Client receives new SSE stream from the POST.\n5. Go to step 1.\n\n#### Rationale\n\nThis feature allows the server to stop execution when input is required from the client.  When the server receives a POST to the `rel=\"stream\"` URL, it can use values embedded in the URL to look up state and resume execution, processing the POSTed input.  Thus load-balanced server instances are able to resume execution and send the result directly to the client without sticky (pinned) sessions.\n\n#### Backward Compatibility\n\n- **New Client + Old Server**: Server will not send a `rel=\"stream\"` URL.  No backward incompatibility as long as client supports the old way of responding to a server-to-client request (POST `/mcp`).\n- **Old Client + New Server**: Client will resume stream with GET `/mcp` and send input with POST `/mcp`.  No backward incompatibility as long as server supports the old way of resuming and sending input.\n","author":{"url":"https://github.com/jonathanhefner","@type":"Person","name":"jonathanhefner"},"datePublished":"2025-08-12T21:00:33.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":38},"url":"https://github.com/1335/modelcontextprotocol/issues/1335"}