feat: expose StreamableHttpHandler for MVC controller support

Make StreamableHttpHandler public so it can be injected into traditional
ASP.NET Core MVC controllers, enabling MCP server scenarios without
minimal APIs.

Changes:
- StreamableHttpHandler: internal -> public, constructor takes IServiceProvider
- Updated WithHttpTransport() XML docs to mention controller injection
- Added 'Using with MVC Controllers' section to AspNetCore README
- New sample: AspNetCoreMcpControllerServer
- New integration tests: McpControllerTests (connect, call tool, list tools)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jtarquino

ModelContextProtocol.slnx

@@ -39,6 +39,7 @@
     <Project Path="docs/concepts/progress/samples/server/Progress.csproj" />
   </Folder>
   <Folder Name="/samples/">
+    <Project Path="samples/AspNetCoreMcpControllerServer/AspNetCoreMcpControllerServer.csproj" />
     <Project Path="samples/AspNetCoreMcpPerSessionTools/AspNetCoreMcpPerSessionTools.csproj" />
     <Project Path="samples/AspNetCoreMcpServer/AspNetCoreMcpServer.csproj" />
     <Project Path="samples/ChatWithTools/ChatWithTools.csproj" />

samples/AspNetCoreMcpControllerServer/AspNetCoreMcpControllerServer.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\ModelContextProtocol.AspNetCore\ModelContextProtocol.AspNetCore.csproj" />
+  </ItemGroup>
+
+</Project>

samples/AspNetCoreMcpControllerServer/Controllers/McpController.cs

@@ -0,0 +1,26 @@
+using Microsoft.AspNetCore.Mvc;
+using ModelContextProtocol.AspNetCore;
+
+namespace AspNetCoreMcpControllerServer.Controllers;
+
+/// <summary>
+/// An MVC controller that handles MCP Streamable HTTP transport requests
+/// by delegating to the <see cref="IStreamableHttpHandler"/> registered by
+/// <c>WithHttpTransport()</c>.
+/// </summary>
+[ApiController]
+[Route("mcp")]
+public class McpController : ControllerBase
+{
+    [HttpPost]
+    public Task Post([FromServices] IStreamableHttpHandler handler) =>
+        handler.HandlePostRequestAsync(HttpContext);
+
+    [HttpGet]
+    public Task Get([FromServices] IStreamableHttpHandler handler) =>
+        handler.HandleGetRequestAsync(HttpContext);
+
+    [HttpDelete]
+    public Task Delete([FromServices] IStreamableHttpHandler handler) =>
+        handler.HandleDeleteRequestAsync(HttpContext);
+}

samples/AspNetCoreMcpControllerServer/Program.cs

@@ -0,0 +1,13 @@
+using AspNetCoreMcpControllerServer.Tools;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddControllers();
+builder.Services.AddMcpServer()
+    .WithHttpTransport()
+    .WithTools<EchoTool>();
+
+var app = builder.Build();
+
+app.MapControllers();
+
+app.Run();

samples/AspNetCoreMcpControllerServer/Properties/launchSettings.json

@@ -0,0 +1,13 @@
+{
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": false,
+      "applicationUrl": "http://localhost:3001",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

samples/AspNetCoreMcpControllerServer/Tools/EchoTool.cs

@@ -0,0 +1,14 @@
+using ModelContextProtocol.Server;
+using System.ComponentModel;
+
+namespace AspNetCoreMcpControllerServer.Tools;
+
+[McpServerToolType]
+public sealed class EchoTool
+{
+    [McpServerTool, Description("Echoes the input back to the client.")]
+    public static string Echo(string message)
+    {
+        return "hello " + message;
+    }
+}

samples/AspNetCoreMcpControllerServer/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

samples/AspNetCoreMcpControllerServer/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}

src/ModelContextProtocol.AspNetCore/HttpMcpServerBuilderExtensions.cs

@@ -29,6 +29,7 @@ public static IMcpServerBuilder WithHttpTransport(this IMcpServerBuilder builder
 
         builder.Services.TryAddSingleton<StatefulSessionManager>();
         builder.Services.TryAddSingleton<StreamableHttpHandler>();
+        builder.Services.TryAddSingleton<IStreamableHttpHandler>(sp => sp.GetRequiredService<StreamableHttpHandler>());
         builder.Services.TryAddSingleton<SseHandler>();
         builder.Services.AddHostedService<IdleTrackingBackgroundService>();
 

src/ModelContextProtocol.AspNetCore/IStreamableHttpHandler.cs

@@ -0,0 +1,68 @@
+using Microsoft.AspNetCore.Http;
+
+namespace ModelContextProtocol.AspNetCore;
+
+/// <summary>
+/// Handles MCP Streamable HTTP transport requests (POST, GET, DELETE) for an ASP.NET Core server.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This handler is registered as a singleton service by <c>WithHttpTransport()</c>
+/// and is used internally by <c>MapMcp()</c> to map MCP endpoints using minimal APIs.
+/// </para>
+/// <para>
+/// It can also be injected directly into MVC controllers or other request-handling code
+/// to support scenarios where minimal APIs are not used:
+/// </para>
+/// <code>
+/// [ApiController]
+/// [Route("mcp")]
+/// public class McpController : ControllerBase
+/// {
+///     [HttpPost]
+///     public Task Post([FromServices] IStreamableHttpHandler handler) =&gt; handler.HandlePostRequestAsync(HttpContext);
+///
+///     [HttpGet]
+///     public Task Get([FromServices] IStreamableHttpHandler handler) =&gt; handler.HandleGetRequestAsync(HttpContext);
+///
+///     [HttpDelete]
+///     public Task Delete([FromServices] IStreamableHttpHandler handler) =&gt; handler.HandleDeleteRequestAsync(HttpContext);
+/// }
+/// </code>
+/// </remarks>
+public interface IStreamableHttpHandler
+{
+    /// <summary>
+    /// Gets the configured <see cref="HttpServerTransportOptions"/> for the MCP server.
+    /// </summary>
+    HttpServerTransportOptions HttpServerTransportOptions { get; }
+
+    /// <summary>
+    /// Handles an MCP Streamable HTTP POST request containing a JSON-RPC message.
+    /// </summary>
+    /// <param name="context">The <see cref="HttpContext"/> for the current request.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    /// <remarks>
+    /// The response will be either a streamed SSE response containing JSON-RPC messages
+    /// or a 202 Accepted response if the request contained only notifications.
+    /// </remarks>
+    Task HandlePostRequestAsync(HttpContext context);
+
+    /// <summary>
+    /// Handles an MCP Streamable HTTP GET request for receiving unsolicited server-to-client messages via SSE.
+    /// </summary>
+    /// <param name="context">The <see cref="HttpContext"/> for the current request.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    /// <remarks>
+    /// This endpoint keeps the connection open and streams SSE events to the client.
+    /// It requires a valid <c>Mcp-Session-Id</c> header and is not available in stateless mode.
+    /// </remarks>
+    Task HandleGetRequestAsync(HttpContext context);
+
+    /// <summary>
+    /// Handles an MCP Streamable HTTP DELETE request to terminate an existing session.
+    /// </summary>
+    /// <param name="context">The <see cref="HttpContext"/> for the current request.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    Task HandleDeleteRequestAsync(HttpContext context);
+}