Add options to keep the state of the existing system

[JeffreySu]

As we discussed in #334, I think as an SDK, during the process of minimal integration, it should not disrupt the default behavior of the original system (unless this SDK is so special that it must do so), for example, the current setting will overwrite the home page (/) of the existing system. I think that more flexible options should be provided in MapMcp() or related methods, whether it is one parameter or an option object, the final effect will be the same.

If the SDK does not handle these issues in the early stage, more developers and projects may face more compatibility adjustments in the later stage.

[halter73]

At first, I thought you might be discussing a way to serialize the MCP server's session state so it could then be encrypted and later restored for use in a "stateless" Streamable HTTP server implementation as I described in the comments of my PR to add stateful server-side Streamable HTTP support

Do you expect this is temporary and will be deleted in the next few weeks, or do you think it'll actually stay around?
I expect this could be temporary if we nail the stateless MCP server experience. The next thing I want to try is a stateless MCP server where the key parts of session state like the ClientInfo and the HttpContext.User's ID is stored in a data protected mcp-session-id similar to a cookie or antiforgery token.

If we feel that is always better than maintaining server-side state in between requests, we can remove this background service, but I suspect a stateful HTTP Streaming transport will still have some advantages like the server being able to make unsolicited requests to the client. While that's pretty niche, it is a capability a stateless server simply wouldn't have. And this isn't breaking new ground. This background service is very similar to SignalR's HttpConnectionManager.Scan.

#330 (comment)

I'm not sure what #334 has to do with state though.

for example, the current setting will overwrite the home page (/) of the existing system.

I provided a WithOrder()-based workaround if you really want to map the SSE endpoint to "/sse" while using "/" for something else.

app.MapMcp("/mcp");
app.MapMcp("/").WithOrder(1); // The higher the order, the lower the priority.
app.MapGet("/", () => "Hello World!"); // Preferred with default order 0. This could be app.MapRazorPages(); instead.

I think that more flexible options should be provided in MapMcp() or related methods, whether it is one parameter or an option object, the final effect will be the same.

If the SDK does not handle these issues in the early stage, more developers and projects may face more compatibility adjustments in the later stage.

I agree WithOrder() isn't the cleanest thing, but I don't want to add extra public API that might soon be deleted when we drop SSE support for Streamable HTTP only. Contrary to your assertion, I think adding these parameters or options now will cause more compatibility issues down the road.

If we drop SSE, MapMcp would then only bind to a single route, since the Streamable HTTP transport has you bind your POST, GET and DELETE handlers all to the same route.

// This would work in a non-SSE future.
// We just delete the line with WithOrder(1) above, but we don't even have to do that.
app.MapMcp("/mcp");
app.MapGet("/", () => "Hello World!"); // This could be app.MapRazorPages(); instead.

[JeffreySu]

What I mean the compatibility problem is not for the code, it should be discovered during compilation while missing such as WithOrder() in the future. The compatibility problem is for the default behavior, as an SDK, it is best not to change any system-level configuration easily; otherwise, it is not a good thing for developers and system reliability.

Of course, in my current practice, the /mcp/xx path has been forcibly added. At least I can start using it now. Thank you very much!

[schaveyt]

@halter73 @JeffreySu Will the PR #392 basically allow one to run the MCP server instance with replicas. For example, if I have 3 replicas for my MCP docker container and my MCP Client (https://cline.bot) starts an SSE session, the SSE session will be able to be maintained across the replicas.

I ran into this yesterday using 0.1.0-preview.7 and it was erroring out...eliminating the replicas solved the session issue.

[halter73]

Will the PR #392 basically allow one to run the MCP server instance with replicas

Yes, but the client will have to support the new "Streamable HTTP" transport to connect to a server in stateless mode. Enabling the stateless mode disables the long-running SSE endpoint, since by enabling stateless mode, you're indicating it's impossible to guarantee that the /message requests will arrive at the same endpoint /sse requst.

Streamable HTTP resolves this issue because JSON-RPC responses (and notifications like progress notifications) are sent directly in the response body of what used to be the /message request, but it does require the client supports it. As you can see, the MCP SDKs are still early in the process of supporting Streamable HTTP, and clients like Cline are generally even slower to get support since they often (but not always) rely on the SDKs. From the looks of it, Cline doesn't support Streamable HTTP yet](cline/cline#2917), so I doubt this will help you yet, but I think it's likely they'll add support sooner or later.

[schaveyt]

Amazing response. Very informative. I am very happy with the current state of things but this is great background to know when I might need to scale

As always. You folks and the community rock 🤘✨