SEP-1287: WebSocket transport for MCP - #1287

I don't think it's critical that a session survives connection disruptions in all cases. It's nice to offer optional support for it, but I don't think we should mandate the server supports it. I imagine many MCP servers are not going to want to deal with managing and cleaning up idle sessions in the background.

One big advantage a session-id-less WebSocket connection has over Streamable HTTP is that you can maintain a long-running session spanning multiple JSON-RPC requests but keep the management of the implicit session super simple by tying the session lifetime directly to the websocket lifetime. You also don't have to worry about dealing with possible duplicate or dropped messages.

We could add something similar to Streamable HTTP's Last-Event-Id support, but that adds a lot of complexity and potential server-side storage requirements. It's also not easy for the server to safefly free its sent message buffers because the client isn't expected to send any ACKs. I think this complexity is the main reason why Last-Event-Id support isn't widely implemented by real MCP servers yet unless their focused on extra long running operations.

A session-id-less WebSocket connection also means don't have to worry about things like session-affinity behind a load balancer since your server simply wouldn't support reconnections. Of course you could simulate this by just returning a -32602 "Invalid mcpSessionId" response to any reconnect attempt, but I think it would be cleaner to have the server just omit the mcpSessionId in this case and make it clear up front that reconnecting is not supported.

keep the management of the implicit session super simple by tying the session lifetime directly to the websocket lifetime

My first MCP server worked this way, but the connection dropped often enough that it was unworkable for any stateful use cases. When you reconnected, you had to re-establish all state, which happened much more often than I expected. The most popular WebSockets client libraries have auto-reconnection, which hides the ephemeral nature of the connection.

So, I resist tying any server state to the connection. Robust reconnection semantics tied to mcpSessionId are a better approach.

As you say, this supports the argument for adding support for Last-Event-Id to this SEP. I just haven't worked through all the trade-offs of various ways to implement Last-Event-Id. I can't simply use the header as HTTP does, since headers are not available anywhere except in the initial WebSocket upgrade request. As you say, this would be easier if notifications were acknowledged. I can work on adding Last-Event-Id to this proposal if you think that would be good enough. Just let me know?

Separately, I could make sessions optional for the WebSocket transport as long as it was clear that you shouldn't tie any state to the connection. In that case, you'd think of the WebSocket transport as a more efficient transport for self-contained request-response usage. However, I suspect that wouldn't help you get on board.

@connor4312, @halter73, and @Kludex, how about this for Last-Event-Id?

1. We add another optional field to notifications, say mcpEventId. I would use a monotonic ULID, but we should only constrain it in the same way an SSE event ID is constrained.
2. The client saves the last of these
3. When a client needs to reconnect and wants all notifications that it missed, it includes an optional mcpEventId field in an initialize call. This means that if the client wants to catch up, it must call initialize. However, as currently written, calling initialize on reconnect is optional, which is helpful because...
4. In the initialize call response, the server somehow acknowledges that it will immediately follow with catchup notifications.
5. The server then starts sending the missed notifications with their mcpEventIds
6. Only after the client receives the mcpEventId that matches their last, does the client send back the notifications/initialized notification to end the initialization phase.

SEP-1364 alt 2 wanted to make this last notification optional, which I think we can still do, but only if the client doesn't want catchup notifications.

Thoughts?

I agree with @halter73 's initial message in this thread.

I think the key motivation is because it's that WebSocket bidirectional protocol, and it makes sense to have MCP as subprotocol.

Let's schedule a call to discuss this.

I'm okay with making sessions optional. However, if you do use them, I feel strongly that the state should be tied to the session, NOT the connection.

I think we should add a reference to this issue: whatwg/html#2177.

Also, I think we should mention that it's more practical to have a single way to send the token.

We could also have a fallback mechanism here and use the proper Authorization header.

OK. I'll put the Authorization header back in. I never should have removed that. I might not get that done before 11am, but we can talk about it as there are two ways.

Please don't! It's all good. I said "could", we can discuss it in the presentation.

OK.

I think we should add a reference to this issue: whatwg/html#2177.

Can you draft an edit for this? I'm not sure where to put it and what point to make? Is the point that the Streamable HTTP transport for browser usage suffers from the same problem when using SSE with EventSource? It's not clear to me that is how people consume the Streamable HTTP transport in browsers. The other option, I can think of would be to establish an HTTP/2 bidirectional stream and parse the SSE package contents (essentially an envelope) without using EventSource. Note, I have no idea if anyone does that. Just expressing my lack of context.

out of curiosity, the current implementations for WS tend to either ship them in query or in cookie, cookie doesn't seem like a valid option here but was query_string considered? In practice there have been some instances where the protocol is logged / monitored, or just blocked.

Yep, I had all four in the original draft: cookies (must be server-set for browser but works), query param, Authorization header, and WebSocket subprotocol smuggling. The feeling was that since the spec defines the minimum that everyone must support meaning every server would have to implement this, we should choose the one way that works for everyone.

I don't feel strongly so would happily change or add to how we can do auth.

I think the bigger worry is that with WebSockets, all of those mechanisms are only available when the connection is made. This makes rotating tokens doable by having the server to close the connection when the token expires but some folks don't like that.

A way to fix that, which was also in the original draft, is to add an envelope that essentially mimics http headers and allows for the transmission of other sideband metadata on every message from the client.

The envelope was objected to because that would force load balancers to parse the JSON.

Again, we are doing this because of browser limitations. I think it's important to mention this, and show reference.

This SHOULD be the same endpoint as the Streamable HTTP transport.

This is likely to be annoying for the Python SDK, and I think for others as well.

Is there a .well-known we are supposed to add those endpoints, or a SEP for it?

In any case, I think it should't be the same.

Fair enough. Should I make it MAY or should I explicitly state that it should be on a different endpoint?

I did a quick search of the spec for that string and the only place ".well-known" shows up in the spec is for authorization so I think it's currently unspecified for transports. We'll need a discussion to decide if/where we want to add it but at first thought I think it actually makes sense to put it near the top of the transport.mdx.

I think it's common to see /ws everywhere, so I would add a SHOULD for this one.

Is the purpose of this limitation to simplify the implementation? I'm not very strong about this, but at least in the Python SDK this wouldn't be an issue - we can handle the validation of both frame formats in ~4 lines of code.

The UTF-8 requirement is copied from the Streamable HTTP transport but I'm guessing you mean the rest of it.

Yes, I favor "ONE GOOD WAY". The less a server must support, the more likely it is to get implemented.

I agree with @halter73 's initial message in this thread.

I think the key motivation is because it's that WebSocket bidirectional protocol, and it makes sense to have MCP as subprotocol.

This part I didn't get it. 🤔

Why would that differ?

What part of "This part"? Those four lines cover a lot of ground.

Message handler not found?

Good catch. That's an uncleaned up artifact of an earlier version where I had multiple things that could be done on the endpoint. I'll remove it but maybe not before 11am.