Document and demonstrate allowed hosts and CORS policy guidance (#1554)

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

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:

docs/concepts/httpcontext/samples/appsettings.json

@@ -5,5 +5,5 @@
       "Microsoft.AspNetCore": "Warning"
     }
   },
-  "AllowedHosts": "*"
+  "AllowedHosts": "localhost;127.0.0.1;[::1]"
 }

docs/concepts/logging/samples/server/appsettings.json

@@ -5,5 +5,5 @@
       "Microsoft.AspNetCore": "Warning"
     }
   },
-  "AllowedHosts": "*"
+  "AllowedHosts": "localhost;127.0.0.1;[::1]"
 }

docs/concepts/progress/samples/server/appsettings.json

@@ -5,5 +5,5 @@
       "Microsoft.AspNetCore": "Warning"
     }
   },
-  "AllowedHosts": "*"
+  "AllowedHosts": "localhost;127.0.0.1;[::1]"
 }

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<string[]>() ?? ["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.

samples/AspNetCoreMcpPerSessionTools/appsettings.json

@@ -6,5 +6,5 @@
       "AspNetCoreMcpPerSessionTools": "Debug"
     }
   },
-  "AllowedHosts": "*"
+  "AllowedHosts": "localhost;127.0.0.1;[::1]"
 }

samples/AspNetCoreMcpServer/Program.cs

@@ -6,6 +6,23 @@ using AspNetCoreMcpServer.Resources;
 using System.Net.Http.Headers;
 
 var builder = WebApplication.CreateBuilder(args);
+var allowedOrigins = builder.Configuration.GetSection("Mcp:AllowedOrigins").Get<string[]>() ?? ["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 @@ builder.Services.AddHttpClient("WeatherApi", client =>
 
 var app = builder.Build();
 
-app.MapMcp();
+app.UseCors();
+app.MapMcp().RequireCors("McpBrowserClient");
 
 app.Run();

samples/AspNetCoreMcpServer/appsettings.json

@@ -5,5 +5,10 @@
       "Microsoft.AspNetCore": "Warning"
     }
   },
-  "AllowedHosts": "*"
+  "AllowedHosts": "localhost;127.0.0.1;[::1]",
+  "Mcp": {
+    "AllowedOrigins": [
+      "http://localhost:5173"
+    ]
+  }
 }

samples/EverythingServer/appsettings.json

@@ -5,5 +5,5 @@
       "Microsoft.AspNetCore": "Warning"
     }
   },
-  "AllowedHosts": "*"
+  "AllowedHosts": "localhost;127.0.0.1;[::1]"
 }

samples/LongRunningTasks/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "localhost;127.0.0.1;[::1]"
+}

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 builder = WebApplication.CreateBuilder(args);
 
 var serverUrl = "http://localhost:7071/";
 var inMemoryOAuthServerUrl = "https://localhost:7029";
+var allowedOrigins = builder.Configuration.GetSection("Mcp:AllowedOrigins").Get<string[]>() ?? ["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 @@ builder.Services.AddHttpClient("WeatherApi", client =>
 
 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}");

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"
+    ]
+  }
+}

tests/ModelContextProtocol.AspNetCore.Tests/MapMcpStreamableHttpTests.cs

@@ -97,6 +97,138 @@ public class MapMcpStreamableHttpTests(ITestOutputHelper outputHelper) : MapMcpT
         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()
     {

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 class ServerConformanceTests(ConformanceServerFixture fixture, ITestOutpu
     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 class ServerConformanceTests(ConformanceServerFixture fixture, ITestOutpu
     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");