SSE required two different route patterns ("/sse" and "/message"), so providing a single RequestDelegate for both would be awkward at best. We could have exposed multiple RequestDelegates. But at that point, why not just use MapMcp()? This request makes a little more sense if you just want to support Streamable HTTP since it's only one route pattern, but it's still three routes in ASP.NET Core internally, since the GET, POST and DELETE endpoints are unique, and UseRouting directs to the right endpoint based on the HTTP method.

Looks like something we could add in the README. In the meanwhile, please take a look at the sample applications in the repo:

It's already in the ModelContextProtocol.AspNetCore README, but not the main one. If we merge #428, the main README will at least cross-reference the AspNetCore README, but it might be a good idea to include an AspNetCore sample right in the main README with a callout that you need the additional AspNetCore package.

A minimal implementation should not have to be concerned with the routing; it should be able to take any HTTP endpoint (where the only guaranteed is that HttpContext will be provided) and turn it into a MCP server. (It is possible since SSE can do this as well.) There are, no examples on how to achieve this. Do we use StreamableHttpServerTransport in some way? I tried using StreamServerTransport with request and response body, and it didn't work.

The StreamServerTransport is most useful for things like in-memory connections simulating stdio connections where there's only a single System.IO.Stream in each direction for the duration of the session, and no need for any HTTP concepts like SSE responses.

The StreamableHttpServerTransport is another lower-level API based on System.IO.Stream, but tuned to the needs of a Streamable HTTP, so it can handle multiple Streams/IDuplexPipes representing multiple requests/responses which you can use to read request bodies and write SSE responses even without an HttpContext.

This is at a slightly lower layer than the TS SDK since netstandard does not provide an HttpContext abstraction to handle things like headers, but fortunately, it doesn't take much code to handle the header stuff. You can look at the StreamableHttpHandler to see how you can use StreamableHttpServerTransport. It's not too much code, and it would be a lot smaller if it didn't have to support both stateful and stateless sessions.

I took a look at TS SDK and it seems to have an example on this. I think C# SDK should follow that as well.

I looked at the TS SDK as well, and I see the fact that it doesn't handle routing for you as a weakness not a strength of that API. StreamableHTTPServerTransport only imports node:http and not express, so it cannot rely on any express routing. All the samples are forced to manually manage the lifetime of the transport, and if you look at samples like simpleStreamableHttp.ts, they are trivially vulnerable to a denial-of-service attack where a client starts a bunch of new sessions without ever calling DELETE growing the transports map until the server process OOMs.

We at least attempt to account for this in MapMcp with our IdleTrackingBackgroundService rather than leave that completely as an exercise to the reader. This isn't a problem for either the csharp-sdk or TS sdk in stateless mode where the transport does not outlive the request, but I think the way we do the stateful version at least is far more developer friendly.

If you really, really want a RequestDelegate, here's the sample code:

var app = builder.Build();

app.MapMcp();

var endpoints = ((IEndpointRouteBuilder)app).DataSources.SelectMany(d => d.Endpoints);
var getDelegate = endpoints.Single(e => e.DisplayName == "MCP Streamable HTTP | HTTP: GET /").RequestDelegate!;
var postDelegate = endpoints.Single(e => e.DisplayName == "MCP Streamable HTTP | HTTP: POST /").RequestDelegate!;
var deleteDelegate = endpoints.Single(e => e.DisplayName == "MCP Streamable HTTP | HTTP: DELETE /").RequestDelegate!;

Task MyMcpRequestDelegate(HttpContext context)
{
    if (string.Equals(context.Request.Method, HttpMethods.Get, StringComparison.OrdinalIgnoreCase))
    {
        return getDelegate(context);
    }
    else if (string.Equals(context.Request.Method, HttpMethods.Post, StringComparison.OrdinalIgnoreCase))
    {
        return postDelegate(context);
    }
    else if (string.Equals(context.Request.Method, HttpMethods.Delete, StringComparison.OrdinalIgnoreCase))
    {
        return deleteDelegate(context);
    }

    context.Response.StatusCode = StatusCodes.Status405MethodNotAllowed;
    return Task.CompletedTask;
}

app.Map("/mymcp", MyMcpRequestDelegate);

app.Run();

You'd be right to point out that the DisplayName for these endpoints are not stable API and could change. But if they do change, Single would throw at startup. So as long as you do a basic smoke test after you upgrade packages, you should be fine.

We could consider an API to make it easier to get this MyMcpRequestDelegate. It would have to come out of DI somehow, because the generated RequestDelegate would have to rely on singleton services like the IdleTrackingBackgroundService which we'd ideally avoid re-retrieving every request. I'm not convinced we need it though. In the above example, you could have just written the following instead.

var app = builder.Build();

app.MapMcp("/mymcp");

app.Run();

Not everything will be that simple, but you might be surprised how flexible MapMcp can be already if paired with things like middleware and/or filters.

Maybe if you share what you were trying to do with MapMcp() which doesn't appear possible without a RequestDelegate, we could evaluate if we really need a RequestDelegate API, if MapMcp() needs to be improved, or if it can meet your needs already.

MapHub, MapGrpcService, MapHealthChecks, etc. do not expose a RequestDelegate directly either as far as I know. So, if we decide it's important to do for MapMcp, I want to understand what makes it special. Or if it's not special, if we should do the same things for those other APIs.

Uh oh!

How to create Streamable HTTP server? #451

Description

Activity

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions