diff --git a/docs/concepts/getting-started.md b/docs/concepts/getting-started.md index f009ec31e..c6096aa60 100644 --- a/docs/concepts/getting-started.md +++ b/docs/concepts/getting-started.md @@ -101,6 +101,20 @@ public static class EchoTool } ``` +#### Host name validation + +For local HTTP servers, keep the set of accepted host names limited to loopback values. This helps protect against DNS rebinding, where a browser reaches a local server through an attacker-controlled DNS name while sending that DNS name in the HTTP `Host` header. ASP.NET Core's Kestrel server doesn't validate `Host` headers by default, so configure `AllowedHosts` with known host names rather than `"*"`. + +For production servers, configure the exact public host names for the deployment, and validate the host name at the proxy or load balancer when one is responsible for forwarding client requests. This also avoids reflecting untrusted host names through ASP.NET Core features such as absolute URL generation. See [Host filtering with ASP.NET Core Kestrel web server | Microsoft Learn](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/host-filtering) and [URL generation concepts | Microsoft Learn](https://learn.microsoft.com/aspnet/core/fundamentals/routing#url-generation-concepts). + +#### Browser cross-origin access + +**Only** enable CORS if you intentionally want browser-based cross-origin access to this server. + +CORS is not a substitute for host name validation. When browser-based cross-origin access is required, limit which browser origins can call the MCP endpoint by using the most restrictive ASP.NET Core CORS policy possible. See [Enable Cross-Origin Requests (CORS) in ASP.NET Core | Microsoft Learn](https://learn.microsoft.com/aspnet/core/security/cors). + +For the full HTTP security examples, including `AllowedHosts` and restrictive CORS on `MapMcp`, see [Streamable HTTP transport](transports/transports.md#browser-cross-origin-access). + ### Building an MCP client Create a new console app, add the package, and replace `Program.cs` with the code below. This client connects to the MCP "everything" reference server, lists its tools, and calls one: diff --git a/docs/concepts/httpcontext/samples/appsettings.json b/docs/concepts/httpcontext/samples/appsettings.json index 10f68b8c8..757d8426e 100644 --- a/docs/concepts/httpcontext/samples/appsettings.json +++ b/docs/concepts/httpcontext/samples/appsettings.json @@ -5,5 +5,5 @@ "Microsoft.AspNetCore": "Warning" } }, - "AllowedHosts": "*" + "AllowedHosts": "localhost;127.0.0.1;[::1]" } diff --git a/docs/concepts/logging/samples/server/appsettings.json b/docs/concepts/logging/samples/server/appsettings.json index 10f68b8c8..757d8426e 100644 --- a/docs/concepts/logging/samples/server/appsettings.json +++ b/docs/concepts/logging/samples/server/appsettings.json @@ -5,5 +5,5 @@ "Microsoft.AspNetCore": "Warning" } }, - "AllowedHosts": "*" + "AllowedHosts": "localhost;127.0.0.1;[::1]" } diff --git a/docs/concepts/progress/samples/server/appsettings.json b/docs/concepts/progress/samples/server/appsettings.json index 10f68b8c8..757d8426e 100644 --- a/docs/concepts/progress/samples/server/appsettings.json +++ b/docs/concepts/progress/samples/server/appsettings.json @@ -5,5 +5,5 @@ "Microsoft.AspNetCore": "Warning" } }, - "AllowedHosts": "*" + "AllowedHosts": "localhost;127.0.0.1;[::1]" } diff --git a/docs/concepts/transports/transports.md b/docs/concepts/transports/transports.md index 57a7c89b9..d0d885114 100644 --- a/docs/concepts/transports/transports.md +++ b/docs/concepts/transports/transports.md @@ -133,6 +133,64 @@ app.Run(); By default, the HTTP transport uses **stateful sessions** — the server assigns an `Mcp-Session-Id` to each client and tracks session state in memory. For most servers, **stateless mode is recommended** instead. It simplifies deployment, enables horizontal scaling without session affinity, and avoids issues with clients that don't send the `Mcp-Session-Id` header. We recommend setting `Stateless` explicitly (rather than relying on the current default) for [forward compatibility](xref:stateless#forward-and-backward-compatibility). See [Sessions](xref:stateless) for a detailed guide on when to use stateless vs. stateful mode, configure session options, and understand [cancellation and disposal](xref:stateless#cancellation-and-disposal) behavior during shutdown. +#### Host name validation + +For local HTTP servers, keep the set of accepted host names limited to loopback values. This helps protect against DNS rebinding, where a browser reaches a local server through an attacker-controlled DNS name while sending that DNS name in the HTTP `Host` header. ASP.NET Core's Kestrel server doesn't validate `Host` headers by default, so configure `AllowedHosts` with known host names rather than `"*"`. This also avoids reflecting untrusted host names through ASP.NET Core features such as absolute URL generation. See [Host filtering with ASP.NET Core Kestrel web server | Microsoft Learn](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/host-filtering) and [URL generation concepts | Microsoft Learn](https://learn.microsoft.com/aspnet/core/fundamentals/routing#url-generation-concepts). + +```json +// appsettings.Development.json +{ + "AllowedHosts": "localhost;127.0.0.1;[::1]" +} +``` + +For production servers, configure `AllowedHosts` to the exact public host names for the deployment. If Kestrel is behind a reverse proxy or load balancer, validate the host name at the layer that receives or forwards the client `Host` header. ASP.NET Core's Host Filtering Middleware is appropriate when Kestrel is public-facing or the `Host` header is directly forwarded; Forwarded Headers Middleware has its own `AllowedHosts` option for cases where the proxy doesn't preserve the original `Host` header. See [Host filtering with ASP.NET Core Kestrel web server | Microsoft Learn](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/host-filtering) and [Configure ASP.NET Core to work with proxy servers and load balancers | Microsoft Learn](https://learn.microsoft.com/aspnet/core/host-and-deploy/proxy-load-balancer). + +If you intentionally expose the server through another host name, such as a tunnel, container host, reverse proxy, or deployed domain, add that exact host name to `AllowedHosts` instead of using `"*"`. + +#### Browser cross-origin access + +**Only** enable CORS if you intentionally want browser-based cross-origin access to this server. + +CORS is not a substitute for host name validation. When browser-based cross-origin access is required, limit which browser origins can call the MCP endpoint by using the most restrictive ASP.NET Core CORS policy possible. See [Enable Cross-Origin Requests (CORS) in ASP.NET Core | Microsoft Learn](https://learn.microsoft.com/aspnet/core/security/cors). + +For a **stateless** browser client, a narrowly scoped CORS policy usually only needs the headers the browser would otherwise preflight: `Content-Type` for JSON, `Authorization` when the endpoint is protected, and `MCP-Protocol-Version`. If you enable sessions or resumability, also allow `Mcp-Session-Id` and `Last-Event-ID`, and expose `Mcp-Session-Id` on responses so browser code can read it. `Accept` normally doesn't need to be listed because browsers can already send it without extra CORS configuration. + + +_In this sample below, the MCP server will allow browser calls from `localhost:5173` where a web application is making the request. In production, this allowed origin list would be configured to the trusted web application domains._ + +```json +// appsettings.Development.json +{ + "Mcp": { + "AllowedOrigins": [ + "http://localhost:5173" + ] + } +} +``` + +```csharp +var allowedOrigins = builder.Configuration.GetSection("Mcp:AllowedOrigins").Get() ?? ["http://localhost:5173"]; + +builder.Services.AddCors(options => +{ + options.AddPolicy("McpBrowserClient", policy => + { + policy.WithOrigins(allowedOrigins) + // Add GET for standalone/resumable SSE streams and DELETE for stateful session termination. + .WithMethods("POST", "GET", "DELETE") + .WithHeaders("Content-Type", "Authorization", "MCP-Protocol-Version", "Mcp-Session-Id") + .WithExposedHeaders("Mcp-Session-Id"); + }); +}); + +var app = builder.Build(); + +app.UseCors(); +app.MapMcp("/mcp").RequireCors("McpBrowserClient"); +``` + #### How messages flow In Streamable HTTP, client requests arrive as HTTP POST requests. The server holds each POST response body open as an SSE stream and writes the JSON-RPC response — plus any intermediate messages like progress notifications or server-to-client requests — back through it. This provides natural HTTP-level backpressure: each POST holds its connection until the handler completes. diff --git a/samples/AspNetCoreMcpPerSessionTools/appsettings.json b/samples/AspNetCoreMcpPerSessionTools/appsettings.json index 88c89fa7d..b70c33e82 100644 --- a/samples/AspNetCoreMcpPerSessionTools/appsettings.json +++ b/samples/AspNetCoreMcpPerSessionTools/appsettings.json @@ -6,5 +6,5 @@ "AspNetCoreMcpPerSessionTools": "Debug" } }, - "AllowedHosts": "*" -} \ No newline at end of file + "AllowedHosts": "localhost;127.0.0.1;[::1]" +} diff --git a/samples/AspNetCoreMcpServer/Program.cs b/samples/AspNetCoreMcpServer/Program.cs index 3b15d07af..f35d0efec 100644 --- a/samples/AspNetCoreMcpServer/Program.cs +++ b/samples/AspNetCoreMcpServer/Program.cs @@ -6,6 +6,23 @@ using System.Net.Http.Headers; var builder = WebApplication.CreateBuilder(args); +var allowedOrigins = builder.Configuration.GetSection("Mcp:AllowedOrigins").Get() ?? ["http://localhost:5173"]; + +// Only enable CORS if you intentionally want browser-based cross-origin access to this server. +// Keep the allowlist narrowly scoped to known origins. Broad CORS settings weaken security. +builder.Services.AddCors(options => +{ + options.AddPolicy("McpBrowserClient", policy => + { + policy.WithOrigins(allowedOrigins) + .WithMethods("GET", "POST", "DELETE") + // Browsers can send Accept without extra CORS configuration. These are the MCP-specific + // and non-safelisted headers the browser-based client needs for stateful Streamable HTTP. + .WithHeaders("Content-Type", "MCP-Protocol-Version", "Mcp-Session-Id") + .WithExposedHeaders("Mcp-Session-Id"); + }); +}); + // Note: This sample uses SampleLlmTool which calls server.AsSamplingChatClient() to send // a server-to-client sampling request. This requires stateful (session-based) mode. Set // Stateless = false explicitly for forward compatibility in case the default changes. @@ -36,6 +53,7 @@ var app = builder.Build(); -app.MapMcp(); +app.UseCors(); +app.MapMcp().RequireCors("McpBrowserClient"); app.Run(); diff --git a/samples/AspNetCoreMcpServer/appsettings.json b/samples/AspNetCoreMcpServer/appsettings.json index 10f68b8c8..7649a2a19 100644 --- a/samples/AspNetCoreMcpServer/appsettings.json +++ b/samples/AspNetCoreMcpServer/appsettings.json @@ -5,5 +5,10 @@ "Microsoft.AspNetCore": "Warning" } }, - "AllowedHosts": "*" + "AllowedHosts": "localhost;127.0.0.1;[::1]", + "Mcp": { + "AllowedOrigins": [ + "http://localhost:5173" + ] + } } diff --git a/samples/EverythingServer/appsettings.json b/samples/EverythingServer/appsettings.json index 10f68b8c8..757d8426e 100644 --- a/samples/EverythingServer/appsettings.json +++ b/samples/EverythingServer/appsettings.json @@ -5,5 +5,5 @@ "Microsoft.AspNetCore": "Warning" } }, - "AllowedHosts": "*" + "AllowedHosts": "localhost;127.0.0.1;[::1]" } diff --git a/samples/LongRunningTasks/appsettings.json b/samples/LongRunningTasks/appsettings.json new file mode 100644 index 000000000..757d8426e --- /dev/null +++ b/samples/LongRunningTasks/appsettings.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning" + } + }, + "AllowedHosts": "localhost;127.0.0.1;[::1]" +} diff --git a/samples/ProtectedMcpServer/Program.cs b/samples/ProtectedMcpServer/Program.cs index 4980e23dd..f539e73bb 100644 --- a/samples/ProtectedMcpServer/Program.cs +++ b/samples/ProtectedMcpServer/Program.cs @@ -1,5 +1,6 @@ using Microsoft.AspNetCore.Authentication.JwtBearer; using Microsoft.IdentityModel.Tokens; +using Microsoft.Net.Http.Headers; using ModelContextProtocol.AspNetCore.Authentication; using ProtectedMcpServer.Tools; using System.Net.Http.Headers; @@ -9,6 +10,26 @@ var serverUrl = "http://localhost:7071/"; var inMemoryOAuthServerUrl = "https://localhost:7029"; +var allowedOrigins = builder.Configuration.GetSection("Mcp:AllowedOrigins").Get() ?? ["http://localhost:5173"]; + +// This sample runs the MCP server on localhost:7071, and it is intended to be callable from a +// companion web app running on a different host (localhost:5173), while preventing requests from +// other origins. This scenario requires enabling CORS and enabling a restrictive CORS policy. +// +// If your server is not meant for cross-origin browser access, leave CORS disabled. +// +// Only apply a lenient CORS policy if your server is intended to be callable from any browser. + +builder.Services.AddCors(options => +{ + options.AddPolicy("McpBrowserClient", policy => + { + policy.WithOrigins(allowedOrigins) + .WithMethods("POST") + .WithHeaders(HeaderNames.ContentType, HeaderNames.Authorization, "MCP-Protocol-Version") + .WithExposedHeaders(HeaderNames.WWWAuthenticate); + }); +}); builder.Services.AddAuthentication(options => { @@ -84,11 +105,12 @@ var app = builder.Build(); +app.UseCors(); app.UseAuthentication(); app.UseAuthorization(); // Use the default MCP policy name that we've configured -app.MapMcp().RequireAuthorization(); +app.MapMcp().RequireAuthorization().RequireCors("McpBrowserClient"); Console.WriteLine($"Starting MCP server with authorization at {serverUrl}"); Console.WriteLine($"Using in-memory OAuth server at {inMemoryOAuthServerUrl}"); diff --git a/samples/ProtectedMcpServer/appsettings.json b/samples/ProtectedMcpServer/appsettings.json new file mode 100644 index 000000000..7649a2a19 --- /dev/null +++ b/samples/ProtectedMcpServer/appsettings.json @@ -0,0 +1,14 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning" + } + }, + "AllowedHosts": "localhost;127.0.0.1;[::1]", + "Mcp": { + "AllowedOrigins": [ + "http://localhost:5173" + ] + } +} diff --git a/tests/ModelContextProtocol.AspNetCore.Tests/MapMcpStreamableHttpTests.cs b/tests/ModelContextProtocol.AspNetCore.Tests/MapMcpStreamableHttpTests.cs index e8df75201..4f2d5aaeb 100644 --- a/tests/ModelContextProtocol.AspNetCore.Tests/MapMcpStreamableHttpTests.cs +++ b/tests/ModelContextProtocol.AspNetCore.Tests/MapMcpStreamableHttpTests.cs @@ -97,6 +97,138 @@ public async Task AutoDetectMode_Works_WithRootEndpoint() Assert.Equal("AutoDetectTestServer", mcpClient.ServerInfo.Name); } + [Fact] + public async Task BrowserPreflight_AllowsConfiguredOrigin_AndRequiredHeaders() + { + Builder.Services.AddCors(options => + { + options.AddPolicy("BrowserClient", policy => + { + policy.WithOrigins("http://localhost:5173") + .WithMethods("GET", "POST", "DELETE") + .WithHeaders("Content-Type", "Authorization", "MCP-Protocol-Version", "Mcp-Session-Id") + .WithExposedHeaders("Mcp-Session-Id"); + }); + }); + + Builder.Services.AddMcpServer().WithHttpTransport(ConfigureStateless); + await using var app = Builder.Build(); + + app.UseCors(); + app.MapMcp().RequireCors("BrowserClient"); + + await app.StartAsync(TestContext.Current.CancellationToken); + + using var request = new HttpRequestMessage(HttpMethod.Options, "http://localhost:5000/"); + request.Headers.Add("Origin", "http://localhost:5173"); + request.Headers.Add("Access-Control-Request-Method", "POST"); + request.Headers.Add("Access-Control-Request-Headers", "content-type,authorization,mcp-protocol-version,mcp-session-id"); + + using var response = await HttpClient.SendAsync(request, TestContext.Current.CancellationToken); + + Assert.Equal(HttpStatusCode.NoContent, response.StatusCode); + Assert.Equal("http://localhost:5173", Assert.Single(response.Headers.GetValues("Access-Control-Allow-Origin"))); + + var allowHeaders = string.Join(",", response.Headers.GetValues("Access-Control-Allow-Headers")); + Assert.Contains("content-type", allowHeaders, StringComparison.OrdinalIgnoreCase); + Assert.Contains("authorization", allowHeaders, StringComparison.OrdinalIgnoreCase); + Assert.Contains("mcp-protocol-version", allowHeaders, StringComparison.OrdinalIgnoreCase); + Assert.Contains("mcp-session-id", allowHeaders, StringComparison.OrdinalIgnoreCase); + } + + [Fact] + public async Task BrowserPreflight_DoesNotCorsApprove_DisallowedOrigin() + { + Builder.Services.AddCors(options => + { + options.AddPolicy("BrowserClient", policy => + { + policy.WithOrigins("http://localhost:5173") + .WithMethods("POST") + .WithHeaders("Content-Type", "MCP-Protocol-Version"); + }); + }); + + Builder.Services.AddMcpServer().WithHttpTransport(ConfigureStateless); + await using var app = Builder.Build(); + + app.UseCors(); + app.MapMcp().RequireCors("BrowserClient"); + + await app.StartAsync(TestContext.Current.CancellationToken); + + using var request = new HttpRequestMessage(HttpMethod.Options, "http://localhost:5000/"); + // CORS matches the browser Origin exactly. "localhost" and "127.0.0.1" both + // resolve to loopback, but they are different origins and do not match. + request.Headers.Add("Origin", "http://127.0.0.1:5173"); + request.Headers.Add("Access-Control-Request-Method", "POST"); + request.Headers.Add("Access-Control-Request-Headers", "content-type,mcp-protocol-version"); + + using var response = await HttpClient.SendAsync(request, TestContext.Current.CancellationToken); + + // ASP.NET Core's CORS middleware commonly answers the preflight with 204 even when + // the origin is not approved. The browser treats the request as disallowed because + // the Access-Control-Allow-* approval headers are omitted from the response. + Assert.Equal(HttpStatusCode.NoContent, response.StatusCode); + Assert.False(response.Headers.Contains("Access-Control-Allow-Origin")); + Assert.False(response.Headers.Contains("Access-Control-Allow-Headers")); + } + + [Fact] + public async Task InitializeResponse_ExposesMcpSessionId_ForBrowserClients() + { + Builder.Services.AddCors(options => + { + options.AddPolicy("BrowserClient", policy => + { + policy.WithOrigins("http://localhost:5173") + .WithMethods("POST") + .WithHeaders("Content-Type", "MCP-Protocol-Version") + .WithExposedHeaders("Mcp-Session-Id"); + }); + }); + + Builder.Services.AddMcpServer(options => + { + options.ServerInfo = new() + { + Name = "CorsSessionServer", + Version = "1.0.0", + }; + }).WithHttpTransport(ConfigureStateless); + await using var app = Builder.Build(); + + app.UseCors(); + app.MapMcp().RequireCors("BrowserClient"); + + await app.StartAsync(TestContext.Current.CancellationToken); + + const string initializeRequest = """ + {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"browser-client","version":"1.0.0"}}} + """; + + using var request = new HttpRequestMessage(HttpMethod.Post, "http://localhost:5000/") + { + Content = new StringContent(initializeRequest, System.Text.Encoding.UTF8, "application/json") + }; + request.Headers.Add("Origin", "http://localhost:5173"); + request.Headers.Accept.ParseAdd("application/json"); + request.Headers.Accept.ParseAdd("text/event-stream"); + + using var response = await HttpClient.SendAsync(request, TestContext.Current.CancellationToken); + + Assert.True(response.IsSuccessStatusCode); + Assert.Equal("http://localhost:5173", Assert.Single(response.Headers.GetValues("Access-Control-Allow-Origin"))); + + var exposedHeaders = string.Join(",", response.Headers.GetValues("Access-Control-Expose-Headers")); + Assert.Contains("Mcp-Session-Id", exposedHeaders, StringComparison.OrdinalIgnoreCase); + + if (!Stateless) + { + Assert.True(response.Headers.Contains("Mcp-Session-Id")); + } + } + [Fact] public async Task SseEndpoints_AreDisabledByDefault_InStatefulMode() { diff --git a/tests/ModelContextProtocol.AspNetCore.Tests/ServerConformanceTests.cs b/tests/ModelContextProtocol.AspNetCore.Tests/ServerConformanceTests.cs index e538a6f3f..adb8e4ac4 100644 --- a/tests/ModelContextProtocol.AspNetCore.Tests/ServerConformanceTests.cs +++ b/tests/ModelContextProtocol.AspNetCore.Tests/ServerConformanceTests.cs @@ -1,4 +1,5 @@ using System.Diagnostics; +using System.Runtime.InteropServices; using System.Text; using ModelContextProtocol.Tests.Utils; @@ -109,6 +110,9 @@ public async Task RunConformanceTests() public async Task RunPendingConformanceTest_JsonSchema202012() { Assert.SkipWhen(!NodeHelpers.IsNodeInstalled(), "Node.js is not installed. Skipping conformance tests."); + Assert.SkipWhen( + RuntimeInformation.IsOSPlatform(OSPlatform.Windows), + "Pending Node-based conformance scenario is unstable on Windows due to a libuv shutdown assertion."); var result = await RunConformanceTestsAsync($"server --url {fixture.ServerUrl} --scenario json-schema-2020-12"); @@ -120,6 +124,9 @@ public async Task RunPendingConformanceTest_JsonSchema202012() public async Task RunPendingConformanceTest_ServerSsePolling() { Assert.SkipWhen(!NodeHelpers.IsNodeInstalled(), "Node.js is not installed. Skipping conformance tests."); + Assert.SkipWhen( + RuntimeInformation.IsOSPlatform(OSPlatform.Windows), + "Pending Node-based conformance scenario is unstable on Windows due to a libuv shutdown assertion."); var result = await RunConformanceTestsAsync($"server --url {fixture.ServerUrl} --scenario server-sse-polling");