Middleware & Endpoints

MapMcp() endpoint configuration and ASP.NET Core middleware integration

The MapMcp() extension method sets up HTTP endpoints for handling MCP Streamable HTTP transport in ASP.NET Core applications.

MapMcp

Maps MCP protocol endpoints to the application’s request pipeline.

public static IEndpointConventionBuilder MapMcp(
    this IEndpointRouteBuilder endpoints,
    string pattern = "")

Parameters

endpoints · IEndpointRouteBuilder · required

The endpoint route builder (typically your WebApplication instance).

pattern · string · default: ""

The route pattern prefix to map MCP endpoints to. Supports ASP.NET Core route templates.

Examples:

• "" - Maps to root path
• "/mcp" - Maps to /mcp
• "/{category}" - Maps with route parameter
• "/api/v1/mcp" - Maps to nested path

Returns

IEndpointConventionBuilder

A builder for configuring endpoint conventions like authorization policies, CORS, rate limiting, and other middleware.

Endpoints Created

The method creates the following endpoints:

Streamable HTTP Transport (2025-11-25 spec)

POST {pattern} · endpoint

Handles MCP client requests. Accepts JSON-RPC messages and may respond with:

• 200 OK with text/event-stream for streaming responses
• 202 Accepted for requests with no immediate response
• 404 Not Found if session ID is invalid

Headers:

• MCP-Protocol-Version (required) - Protocol version (e.g., “2025-11-25”)
• Mcp-Session-Id (optional) - Session identifier for stateful mode
• Last-Event-ID (optional) - For resuming interrupted streams

Content-Type: application/json

Accept: Must include both application/json and text/event-stream

GET {pattern} · endpoint

Opens a persistent SSE stream for receiving server-to-client messages and requests.

Not available in stateless mode.

Headers:

• Mcp-Session-Id (required) - Session identifier
• Last-Event-ID (optional) - For resuming from a specific event

Response: 200 OK with text/event-stream

DELETE {pattern} · endpoint

Explicitly terminates an MCP session and cleans up resources.

Not available in stateless mode.

Headers:

• Mcp-Session-Id (required) - Session identifier to delete

Legacy HTTP with SSE Transport (2024-11-05 spec)

GET {pattern}/sse · endpoint

Legacy SSE endpoint for backward compatibility.

Not available in stateless mode.

Response: 200 OK with text/event-stream

POST {pattern}/message · endpoint

Legacy message endpoint for backward compatibility.

Not available in stateless mode.

Content-Type: application/json

Response: 202 Accepted

Basic Usage

Minimal Setup

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMcpServer()
    .WithHttpTransport()
    .WithTools<MyTools>();

var app = builder.Build();

app.MapMcp();

app.Run();

Authorization

Apply authorization policies to MCP endpoints using the returned IEndpointConventionBuilder.

Require Authentication

app.MapMcp()
    .RequireAuthorization();

Tool-Level Authorization

For granular authorization on individual tools, prompts, or resources:

builder.Services.AddMcpServer()
    .WithHttpTransport()
    .AddAuthorizationFilters()
    .WithTools<MyTools>();

// In your tool class
public class MyTools
{
    [McpServerTool("admin_tool")]
    [Authorize("AdminOnly")]
    public static string AdminOperation()
    {
        return "Admin operation completed";
    }

    [McpServerTool("public_tool")]
    [AllowAnonymous]
    public static string PublicOperation()
    {
        return "Public operation completed";
    }
}

CORS Configuration

Enable CORS for cross-origin MCP clients:

Basic CORS

builder.Services.AddCors(options =>
{
    options.AddDefaultPolicy(policy =>
    {
        policy.WithOrigins("https://client.example.com")
              .AllowAnyMethod()
              .AllowAnyHeader();
    });
});

var app = builder.Build();
app.UseCors();

app.MapMcp();

Rate Limiting

Protect MCP endpoints with rate limiting:

using System.Threading.RateLimiting;

builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("mcpLimit", config =>
    {
        config.PermitLimit = 100;
        config.Window = TimeSpan.FromMinutes(1);
        config.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        config.QueueLimit = 10;
    });
});

var app = builder.Build();
app.UseRateLimiter();

app.MapMcp()
    .RequireRateLimiting("mcpLimit");

Per-Session Configuration

Combine route parameters with session configuration:

Category-Based Tools

builder.Services.AddMcpServer()
    .WithHttpTransport(options =>
    {
        options.ConfigureSessionOptions = async (httpContext, mcpOptions, ct) =>
        {
            var category = httpContext.Request.RouteValues["category"]?.ToString();
            
            // Filter tools based on category
            if (category == "calculator")
            {
                mcpOptions.Capabilities = new();
                mcpOptions.Capabilities.Tools = new();
                mcpOptions.ToolCollection = [/* calculator tools */];
            }
        };
    });

var app = builder.Build();
app.MapMcp("/{category}");

Multiple MCP Endpoints

Host multiple MCP servers with different configurations:

var app = builder.Build();

// Public MCP endpoint
app.MapMcp("/public")
    .AllowAnonymous();

// Admin MCP endpoint
app.MapMcp("/admin")
    .RequireAuthorization("AdminPolicy");

// API versioned endpoint
app.MapMcp("/api/v1/mcp");

app.Run();

Metadata and OpenAPI

Enrich endpoints with metadata for OpenAPI documentation:

app.MapMcp()
    .WithName("McpEndpoint")
    .WithDisplayName("Model Context Protocol")
    .WithDescription("MCP server for AI tool integration")
    .WithTags("MCP", "AI", "Tools")
    .WithOpenApi();

Error Handling

The endpoints automatically handle errors and return JSON-RPC error responses:

• 400 Bad Request - Invalid protocol version or malformed JSON-RPC
• 404 Not Found - Session not found or expired
• 406 Not Acceptable - Missing required Accept headers

Custom error handling can be added via middleware:

app.Use(async (context, next) =>
{
    try
    {
        await next();
    }
    catch (Exception ex)
    {
        if (context.Request.Path.StartsWithSegments("/mcp"))
        {
            // Custom MCP error logging
            logger.LogError(ex, "MCP endpoint error");
        }
        throw;
    }
});

app.MapMcp("/mcp");

Prerequisites

MapMcp() requires that WithHttpTransport() has been called during service registration. Calling MapMcp() without proper service configuration will throw an InvalidOperationException.

// Required service registration
builder.Services.AddMcpServer()
    .WithHttpTransport(); // This must be called first

var app = builder.Build();

// Now you can map endpoints
app.MapMcp();

Protocol Specifications

The endpoints implement:

• Streamable HTTP Transport (2025-11-25)
• HTTP with SSE Transport (2024-11-05 - legacy)

Supported protocol versions:

• 2024-11-05
• 2025-03-26
• 2025-06-18
• 2025-11-25