chore(mcp): document stateless transport posture and remove SseKeepAliveMiddleware

src/Elastic.Documentation.ServiceDefaults/AppDefaultsExtensions.cs

@@ -13,6 +13,7 @@
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Extensions.Diagnostics.HealthChecks;
 using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Http.Resilience;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Console;
 
@@ -36,7 +37,10 @@ public static TBuilder AddDocumentationServiceDefaults<TBuilder>(
 			.AddElasticDocumentationLogging(cliOptions.LogLevel)
 			.ConfigureHttpClientDefaults(http =>
 			{
-				_ = http.AddStandardResilienceHandler();
+				_ = http.AddStandardResilienceHandler(options =>
+				{
+					options.Retry.DisableForUnsafeHttpMethods();
+				});
 			})
 			.AddConfigurationFileProvider(cliOptions.SkipPrivateRepositories, cliOptions.ConfigSource, (s, p) =>
 			{

src/api/Elastic.Documentation.Mcp.Remote/Program.cs

@@ -51,17 +51,18 @@
 	profile.RegisterAllServices(builder.Services);
 
 	// CreateSlimBuilder disables reflection-based JSON serialization.
-	// The MCP SDK's legacy SSE handler uses Results.BadRequest(string) which needs
-	// ASP.NET Core's HTTP JSON options to have type metadata for System.String.
+	// McpJsonUtilities registers System.String so the SDK's error responses can serialize.
 	_ = builder.Services.ConfigureHttpJsonOptions(options =>
 	{
 		options.SerializerOptions.TypeInfoResolverChain.Insert(0, McpJsonUtilities.DefaultOptions.TypeInfoResolver!);
 	});
 
-	// Stateless mode: no Mcp-Session-Id header is issued or expected, which avoids a known
-	// Cursor bug where it opens the SSE stream without the session header and receives 400.
-	// Stateless mode is appropriate here because all tools are pure request/response (no
-	// server-initiated push) and the server runs behind a load balancer without session affinity.
+	// Stateless Streamable HTTP transport: each request is an independent POST / — no session
+	// affinity, no Mcp-Session-Id header, no server-initiated push (sampling/elicitation/roots).
+	// This is the correct posture for a load-balanced service whose tools are pure request/response.
+	// In SDK 1.4+, stateless and SSE are mutually exclusive; EnableLegacySse (default false)
+	// cannot be combined with Stateless = true. SSE-only clients should use the mcp-remote bridge:
+	// npx -y mcp-remote https://<host>/docs/_mcp
 	var mcpBuilder = builder.Services
 		.AddMcpServer(options => options.ServerInstructions = profile.ComposeServerInstructions())
 		.WithHttpTransport(o => o.Stateless = true);
@@ -92,7 +93,6 @@
 		}));
 
 	_ = app.UseMiddleware<McpBearerAuthMiddleware>();
-	_ = app.UseMiddleware<SseKeepAliveMiddleware>();
 
 	var mcpPrefix = SystemEnvironmentVariables.Instance.McpPrefix;
 	var mcp = app.MapGroup(mcpPrefix);