fix(transport): exempt initialize requests from MCP-Protocol-Version checks

Per the Streamable HTTP spec the MCP-Protocol-Version header is required only after initialization completes; version selection for initialize happens through body-level negotiation, not header validation.

* Client: stop sending MCP-Protocol-Version on initialize requests

* Servlet servers: skip strict header validation for initialize so clients advertising an unsupported version negotiate instead of getting 400

* Tests: pin client omission and server tolerance for initialize; make version-negotiation test contextExtractor null-safe for absent headers

Author: slachiewicz

mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java

@@ -543,9 +543,17 @@ public Mono<Void> sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 				var builder = requestBuilder.uri(uri)
 					.header(HttpHeaders.ACCEPT, APPLICATION_JSON + ", " + TEXT_EVENT_STREAM)
 					.header(HttpHeaders.CONTENT_TYPE, APPLICATION_JSON_UTF8)
-					.header(HttpHeaders.CACHE_CONTROL, "no-cache")
-					.header(HttpHeaders.PROTOCOL_VERSION, ctx.getOrDefault(McpAsyncClient.NEGOTIATED_PROTOCOL_VERSION,
-							this.latestSupportedProtocolVersion));
+					.header(HttpHeaders.CACHE_CONTROL, "no-cache");
+				// Per the Streamable HTTP transport spec, the MCP-Protocol-Version header
+				// is required on all requests after initialization completes. The
+				// initialize request itself carries no negotiated version yet -- the
+				// client's supported versions are conveyed in the request body for
+				// server-side negotiation -- so the header must not be sent.
+				if (!(sentMessage instanceof McpSchema.JSONRPCRequest jsonrpcMessage
+						&& McpSchema.METHOD_INITIALIZE.equals(jsonrpcMessage.method()))) {
+					builder = builder.header(HttpHeaders.PROTOCOL_VERSION, ctx
+						.getOrDefault(McpAsyncClient.NEGOTIATED_PROTOCOL_VERSION, this.latestSupportedProtocolVersion));
+				}
 				// Per SEP-2243, mirror the JSON-RPC method and, where applicable, the
 				// target name/URI in dedicated headers so the server can validate
 				// them without parsing the body.

mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java

@@ -163,10 +163,6 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 			return;
 		}
 
-		if (!validateProtocolVersion(request, response)) {
-			return;
-		}
-
 		try {
 			Map<String, List<String>> headers = HttpServletRequestUtils.extractHeaders(request);
 			this.securityValidator.validateHeaders(headers);
@@ -192,6 +188,16 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 
 			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body);
 
+			// The MCP-Protocol-Version header can only be strictly validated once a
+			// version has been negotiated; during 'initialize' the client advertises its
+			// versions in the request body and any header value is resolved by regular
+			// version negotiation instead of being rejected.
+			boolean initializationRequest = message instanceof McpSchema.JSONRPCRequest initRequestCheck
+					&& McpSchema.METHOD_INITIALIZE.equals(initRequestCheck.method());
+			if (!initializationRequest && !validateProtocolVersion(request, response)) {
+				return;
+			}
+
 			// Per SEP-2243, reject header/body mismatches (missing headers are tolerated
 			// so legacy clients keep working).
 			if (!validateMcpHeaders(request, response, message)) {
@@ -282,7 +288,9 @@ private void responseError(HttpServletResponse response, int httpCode, McpError
 	 * Validates the {@code MCP-Protocol-Version} header against the protocol versions
 	 * supported by this transport. A missing header is allowed and falls back to the
 	 * negotiated protocol version, while a header carrying an unsupported version is
-	 * rejected with a 400 Bad Request.
+	 * rejected with a 400 Bad Request. Initialize requests are exempt: no version has
+	 * been negotiated yet, so any header value carried on them is resolved through
+	 * regular body-based version negotiation.
 	 * @param request the HTTP servlet request
 	 * @param response the HTTP servlet response
 	 * @return true if the header is missing or contains a supported version, false if a

mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java

@@ -417,10 +417,6 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 			return;
 		}
 
-		if (!validateProtocolVersion(request, response)) {
-			return;
-		}
-
 		try {
 			Map<String, List<String>> headers = HttpServletRequestUtils.extractHeaders(request);
 			this.securityValidator.validateHeaders(headers);
@@ -447,6 +443,16 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 
 			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body);
 
+			// The MCP-Protocol-Version header can only be strictly validated once a
+			// version has been negotiated; during 'initialize' the client advertises its
+			// versions in the request body and any header value is resolved by the
+			// regular version negotiation below instead of being rejected.
+			boolean initializationRequest = message instanceof McpSchema.JSONRPCRequest initRequestCheck
+					&& McpSchema.METHOD_INITIALIZE.equals(initRequestCheck.method());
+			if (!initializationRequest && !validateProtocolVersion(request, response)) {
+				return;
+			}
+
 			// Per SEP-2243, reject header/body mismatches (missing headers are tolerated
 			// so
 			// legacy clients keep working).
@@ -676,7 +682,9 @@ public void responseError(HttpServletResponse response, int httpCode, McpError m
 	 * Validates the {@code MCP-Protocol-Version} header against the protocol versions
 	 * supported by this transport. A missing header is allowed and falls back to the
 	 * negotiated protocol version, while a header carrying an unsupported version is
-	 * rejected with a 400 Bad Request.
+	 * rejected with a 400 Bad Request. Initialize requests are exempt: no version has
+	 * been negotiated yet, so any header value carried on them is resolved through
+	 * regular body-based version negotiation.
 	 * @param request the HTTP servlet request
 	 * @param response the HTTP servlet response
 	 * @return true if the header is missing or contains a supported version, false if a

mcp-test/src/test/java/io/modelcontextprotocol/client/transport/Sep2243ClientRequestHeaderTests.java

@@ -7,6 +7,7 @@
 import com.sun.net.httpserver.HttpServer;
 import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import java.io.IOException;
 import java.net.InetSocketAddress;
 import java.util.Map;
@@ -93,4 +94,43 @@ void emitsMcpMethodForNotification() throws IOException {
 		}
 	}
 
-}
+	@Test
+	void omitsMcpProtocolVersionHeaderOnInitializeRequest() throws IOException {
+		var seenProtocolVersions = new java.util.concurrent.CopyOnWriteArrayList<String>();
+		var server = HttpServer.create(new InetSocketAddress(0), 0);
+
+		try {
+			server.createContext("/mcp", exchange -> {
+				seenProtocolVersions.add(exchange.getRequestHeaders().getFirst(HttpHeaders.PROTOCOL_VERSION));
+				exchange.getRequestBody().readAllBytes();
+				exchange.sendResponseHeaders(202, -1);
+				exchange.close();
+			});
+			server.start();
+
+			var transport = HttpClientStreamableHttpTransport
+				.builder("http://localhost:" + server.getAddress().getPort())
+				.endpoint("/mcp")
+				.supportedProtocolVersions(java.util.List.of(ProtocolVersions.MCP_2025_11_25, "2263-03-18"))
+				.build();
+
+			try {
+				// The initialize request carries the client's latest supported version in
+				// its body for negotiation; sending an MCP-Protocol-Version header would
+				// make strict servers reject it before negotiation happens.
+				var initRequest = new McpSchema.JSONRPCRequest(McpSchema.METHOD_INITIALIZE, "test-id",
+						Map.of("protocolVersion", "2263-03-18"));
+				StepVerifier.create(transport.sendMessage(initRequest)).verifyComplete();
+			}
+			finally {
+				StepVerifier.create(transport.closeGracefully()).verifyComplete();
+			}
+
+			assertThat(seenProtocolVersions).containsNull();
+		}
+		finally {
+			server.stop(0);
+		}
+	}
+
+}

mcp-test/src/test/java/io/modelcontextprotocol/common/HttpClientStreamableHttpVersionNegotiationIntegrationTests.java

@@ -6,6 +6,7 @@
 
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.function.BiFunction;
 
 import io.modelcontextprotocol.client.McpClient;
@@ -37,8 +38,10 @@ class HttpClientStreamableHttpVersionNegotiationIntegrationTests {
 
 	private final HttpServletStreamableServerTransportProvider transport = HttpServletStreamableServerTransportProvider
 		.builder()
-		.contextExtractor(
-				req -> McpTransportContext.create(Map.of("protocol-version", req.getHeader("MCP-protocol-version"))))
+		// The MCP-Protocol-Version header may legitimately be absent on initialize
+		// requests, so a missing header must not break context extraction.
+		.contextExtractor(req -> McpTransportContext
+			.create(Map.of("protocol-version", Objects.requireNonNullElse(req.getHeader("MCP-protocol-version"), ""))))
 		.build();
 
 	private final McpSchema.Tool toolSpec = McpSchema.Tool.builder("test-tool")

mcp-test/src/test/java/io/modelcontextprotocol/server/transport/Sep2243ServerHeaderValidationTests.java

@@ -138,4 +138,33 @@ void statelessToleratesAbsentHeaders() throws Exception {
 				"Mcp-Name header");
 	}
 
+	// --- Initialize requests must not be rejected on MCP-Protocol-Version ------------
+
+	private static byte[] initializeBody() throws Exception {
+		var request = new McpSchema.JSONRPCRequest(McpSchema.METHOD_INITIALIZE, "test-id",
+				Map.of("protocolVersion", "2263-03-18"));
+		return McpJsonMapperUtils.JSON_MAPPER.writeValueAsString(request).getBytes(StandardCharsets.UTF_8);
+	}
+
+	@Test
+	void streamableToleratesUnsupportedProtocolVersionOnInitialize() throws Exception {
+		var provider = HttpServletStreamableServerTransportProvider.builder().mcpEndpoint("/mcp").build();
+
+		// During initialization no protocol version has been negotiated yet, so any
+		// header value must be resolved through regular version negotiation instead of
+		// a hard 400.
+		var resp = invoke(provider, "/mcp", Map.of(HttpHeaders.PROTOCOL_VERSION, "junk"), initializeBody());
+
+		assertThat(resp.getContentAsString()).doesNotContain("Unsupported protocol version");
+	}
+
+	@Test
+	void statelessToleratesUnsupportedProtocolVersionOnInitialize() throws Exception {
+		var transport = HttpServletStatelessServerTransport.builder().messageEndpoint("/mcp").build();
+
+		var resp = invoke(transport, "/mcp", Map.of(HttpHeaders.PROTOCOL_VERSION, "junk"), initializeBody());
+
+		assertThat(resp.getContentAsString()).doesNotContain("Unsupported protocol version");
+	}
+
 }