Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/modelcontextprotocol/csharp-sdk/llms.txt

Use this file to discover all available pages before exploring further.

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/jsonAccept: 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/jsonResponse: 202 Accepted

​
Basic Usage

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. 
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: 
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: 
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: Supported protocol versions:
  • 2024-11-05
  • 2025-03-26
  • 2025-06-18
  • 2025-11-25

Build docs developers (and LLMs) love

Get started for freeTalk to us