How to create Streamable HTTP server?

[Voileexperiments]

All examples are based on STDIO transport. There are no examples that demonstrates how to expose an HTTP server with an endpoint serving an MCP server.

[eiriktsarpalis]

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

https://github.com/modelcontextprotocol/csharp-sdk/blob/adb2098e4d847ae6075f98a06b8fbca8c057f6cb/samples/AspNetCoreSseServer/Program.cs

[Voileexperiments]

That's actually what caused me to raise this issue: the example relies on .MapMcp(), which couples routing with the server itself.

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.

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.

[halter73]

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.

[Voileexperiments]

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.

I think the whole disucssion is making the assumption that ASP.NET Core has to be used just to set up an HTTP MCP server. Currently if I want to set up an MCP server on C#, besides ModelContextProtocol I'd also somehow need ModelContextProtocol.AspNetCore just to route the requests properly. This is problematic because C# is not ASP.NET Core; in fact ModelContextProtocol support .NET Standard 2.0 (ModelContextProtocol.AspNetCore isn't), so all use cases that ModelContextProtocol support should still work on .NET Framework, which can't use ModelContextProtocol.AspNetCore but can still use ModelContextProtocol. If HTTP MCP server is bundled with MapMcp or equal ASP.NET Core constructs, it locks HTTP MCP server out of .NET Framework.

[Agazoth]

Adding the RequestDelegate sample code to my HttpSSE server turned it into a Streamable Http server that can be used in Copilot Studio and it still works as a HttpSSE server in our other clients.

[halter73]

Adding the RequestDelegate sample code to my HttpSSE server turned it into a Streamable Http server that can be used in Copilot Studio and it still works as a HttpSSE server in our other clients.

I'm surprised that the "/mymcp" endpoint in my sample works any differently than the "/" endpoint. MapMcp already supports both Streamable HTTP and SSE in a single call, just at different endpoints, "/" and "/sse" respectively.

Sets up endpoints for handling MCP Streamable HTTP transport. See the 2025-03-26 protocol specification for details about the Streamable HTTP transport. Also maps legacy SSE endpoints for backward compatibility at the path "/sse" and "/message". the 2024-11-05 protocol specification for details about the HTTP with SSE transport.

MapMcp API Documentation

@Agazoth Is it possible you we're trying the wrong endpoint with Copilot Studio? Maybe you were trying "/sse" instead. If you were trying the "/" endpoint and it wasn't working, do you know what was different about the "/mymcp" endpoint that made it work?

[Agazoth]

@halter73 you are right!

I removed the delegation code and connected to the endpoint without anything in basepath (/). Streaming Http works as expected now. I think I got sidetracked because custom connectors take their sweet time to connect to the endpoint.

Thanks for clearing this up.

[ksaye]

@Agazoth, can you share the working sample that you used for MCS (Copilot Studio) and the swagger? I am attempting this and I am a little lost.

I was assuming the code below:

// Program.cs
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMcpServer()
    .WithHttpTransport()
    .WithToolsFromAssembly();
var app = builder.Build();

app.MapMcp("/");

// using DevTunnel
app.Run("http://localhost:8000");

[McpServerToolType]
public static class EchoTool
{
    [McpServerTool, Description("Echoes the message back to the client.")]
    public static string Echo(string message) => $"hello {message}";
}

With the swagger (for the Custom Connector):

swagger: '2.0'
info:
  title: MCP
  description: Provides the ability to ******
  version: '1.0'
host: g9******b.usw3.devtunnels.ms:8000
basePath: /
schemes:
  - https
definitions:
  message:
    type: string
paths:
  /:
    get:
      summary: Voice Agent Echo
      parameters:
        - in: query
          name: message
          type: string
          required: true
      produces:
        - application/json
      responses:
        '200':
          description: message
          schema:
            $ref: '#/definitions/message'
        '201':
          description: Created and will follow callback
      operationId: echo
      tags:
        - echo
securityDefinitions: {}

The response I get when I test is:

{
  "error": {
    "code": -32001,
    "message": "Session not found"
  },
  "id": "",
  "jsonrpc": "2.0"
}

What am I missing? [other than knowledge and experience]

[halter73]

I haven't personally tested integration with Copilot Studio, but it appears it's treating the MCP endpoint as a generic REST endpoint which makes sense given the swagger. Based on the docuemtnation, your swagger should probably look more like this:

swagger: '2.0'
info:
  title: MCP
  description: Provides the ability to ******
  version: '1.0'
host: g9******b.usw3.devtunnels.ms:8000
basePath: /
schemes:
  - https
paths:
  /:
    post:
      summary: Voice Agent Echo
      x-ms-agentic-protocol: mcp-streamable-1.0
      operationId: echo

https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-mcp#mcp-server-schema-examples

[Agazoth]

@ksaye MCP your code is good. I tested it in both vs code and inspector. As @halter73 points out, the issue must be with your swagger configuration. I have tested the following swagger in Power Apps Custom Connections and can connect to the the Echo mcp with it:

swagger: '2.0'
info:
  title: MCP Server
  description: >-
    This MCP Server will work with Streamable HTTP and is meant to work with
    Microsoft Copilot Studio
  version: 1.0.0
host: h4dwtime-666s.euw.devtunnels.ms
basePath: /
schemes:
  - https
consumes: []
produces: []
paths:
  /:
    post:
      summary: MCP Server Streamable HTTP
      x-ms-agentic-protocol: mcp-streamable-1.0
      operationId: InvokeServer
      responses: {}
definitions: {}
parameters: {}
responses: {}
tags: []
securityDefinitions: {}

I use the MCP-Streamable-HTTP template and removed the security parameter (you do not use it in your code). All you need is to tell the connection where to find the MCP server. The port number is not required either. Post is what differentiates Streaming-HTTP from SSE - SSE uses Get.

In Inspector you can also run your server code with the SSE transport type, you just have to append sse to your uri.

The really cool thing in the MCP Server/Client setup is, that the server advertises its tools to the client, so devs don't have to specify the tools both in their code and in the configuration for the agents consuming the server.

[ksaye]

Thanks both @Agazoth and @halter73

@Agazoth, thanks for the pointers and how did you test in Power Apps? I see the InvokeServer and see the error coming back, but how did you send a message and get a successful response? I am throwing errors:

[Agazoth]

Never got the test in the custom connector running, but if you test in swagger you get a less angry error (cors something ...). And then you can test successfully in Agent -> Tools

[ksaye]

Never got the test in the custom connector running, but if you test in swagger you get a less angry error (cors something ...). And then you can test successfully in Agent -> Tools

That was my next step (Copilot Studio).

Using the Swagger:

swagger: '2.0'
info:
  title: MCP Server
  description: >-
    This MCP Server will work with Streamable HTTP and is meant to work with
    Microsoft Copilot Studio
  version: 1.0.0
host: l0******2.usw3.devtunnels.ms
basePath: /
schemes:
  - https
consumes: []
produces: []
paths:
  /mcp:
    post:
      summary: MCP Server Streamable HTTP
      x-ms-agentic-protocol: mcp-streamable-1.0
      operationId: InvokeServer
      responses: {}
definitions: {}
parameters: {}
responses: {}
tags: []
securityDefinitions: {}

I cannot enumerate or use the tools, as shown below. Are you able to see them and are you sure it is not using SSE? [on that topic, how can I enable SSE with the super simple code above]?

[Agazoth]

When executing from the custom connection swagger editor in Power Apps it looks like this:

Then, when setting the tool up on an Agent it looks like this:

It takes some time to refresh the first time, but the tool is available.

Inspector is a great tool to test the server before proceeding to the Power universe. You can find it here: https://www.npmjs.com/package/@modelcontextprotocol/inspector

All you need is node.js and then you can run npx @modelcontextprotocol/inspector

It spins up a MCP Client that lets you test individual tools in a MCP Server:

And you get a nice log in your terminal:

[ksaye]

2 small updates.

1. My issue why Copilot could not see the tools was that my environment was not deployed with the 'Get New Features Early' setting, required as of now for the HTTP Streamable

2. When deployed in Azure as a web app, I had to set the minimum inbound TLS to 1.2