Send Mcp-Method header on Streamable HTTP client requests (SEP-2243)

The streamable HTTP client transport now mirrors the JSON-RPC method of
outgoing requests and notifications into the Mcp-Method HTTP header, as
required by SEP-2243. Responses do not carry a method and are sent
without the header.

Signed-off-by: Nikita Kibitkin <nikita.n.kibitkin@gmail.com>

Author: nikita-kibitkin

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

@@ -503,6 +503,13 @@ public Mono<Void> sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 							transportSession.sessionId().get());
 				}
 
+				if (sentMessage instanceof McpSchema.JSONRPCRequest request) {
+					requestBuilder = requestBuilder.header(HttpHeaders.MCP_METHOD, request.method());
+				}
+				else if (sentMessage instanceof McpSchema.JSONRPCNotification notification) {
+					requestBuilder = requestBuilder.header(HttpHeaders.MCP_METHOD, notification.method());
+				}
+
 				var builder = requestBuilder.uri(uri)
 					.header(HttpHeaders.ACCEPT, APPLICATION_JSON + ", " + TEXT_EVENT_STREAM)
 					.header(HttpHeaders.CONTENT_TYPE, APPLICATION_JSON_UTF8)

mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java

@@ -26,6 +26,13 @@ public interface HttpHeaders {
 	 */
 	String PROTOCOL_VERSION = "MCP-Protocol-Version";
 
+	/**
+	 * Mirrors the JSON-RPC method of the request or notification carried in the body.
+	 * @see <a href=
+	 * "https://modelcontextprotocol.io/seps/2243-http-standardization">SEP-2243</a>
+	 */
+	String MCP_METHOD = "Mcp-Method";
+
 	/**
 	 * The HTTP Content-Length header.
 	 * @see <a href=

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

@@ -7,23 +7,27 @@
 import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpTransportSessionClosedException;
 import io.modelcontextprotocol.spec.ProtocolVersions;
 import java.net.URI;
 import java.net.URISyntaxException;
+import java.net.http.HttpRequest;
 import java.util.Map;
 import java.util.function.Consumer;
 import java.util.function.Function;
 
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.containers.wait.strategy.Wait;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.atLeastOnce;
@@ -166,4 +170,99 @@ void testCloseInitialized() {
 			.verify();
 	}
 
+	@Test
+	void testMcpMethodHeaderOnRequest() throws URISyntaxException {
+		var uri = new URI(host + "/mcp");
+		var mockRequestCustomizer = mock(McpSyncHttpClientRequestCustomizer.class);
+
+		var transport = HttpClientStreamableHttpTransport.builder(host)
+			.httpRequestCustomizer(mockRequestCustomizer)
+			.build();
+
+		withTransport(transport, (t) -> {
+			var initializeRequest = McpSchema.InitializeRequest
+				.builder(ProtocolVersions.MCP_2025_11_25, McpSchema.ClientCapabilities.builder().roots(true).build(),
+						McpSchema.Implementation.builder("MCP Client", "0.3.1").build())
+				.build();
+			var testMessage = new McpSchema.JSONRPCRequest(McpSchema.METHOD_INITIALIZE, "test-id", initializeRequest);
+
+			StepVerifier
+				.create(t.sendMessage(testMessage).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)))
+				.verifyComplete();
+
+			var requestCaptor = ArgumentCaptor.forClass(HttpRequest.Builder.class);
+			verify(mockRequestCustomizer, atLeastOnce()).customize(requestCaptor.capture(), eq("POST"), eq(uri), any(),
+					eq(context));
+			assertThat(requestCaptor.getValue().build().headers().firstValue(HttpHeaders.MCP_METHOD))
+				.hasValue(McpSchema.METHOD_INITIALIZE);
+		});
+	}
+
+	@Test
+	void testMcpMethodHeaderOnNotification() throws URISyntaxException {
+		var uri = new URI(host + "/mcp");
+		var mockRequestCustomizer = mock(McpSyncHttpClientRequestCustomizer.class);
+
+		var transport = HttpClientStreamableHttpTransport.builder(host)
+			.httpRequestCustomizer(mockRequestCustomizer)
+			.build();
+
+		withTransport(transport, (t) -> {
+			var initializeRequest = McpSchema.InitializeRequest
+				.builder(ProtocolVersions.MCP_2025_11_25, McpSchema.ClientCapabilities.builder().roots(true).build(),
+						McpSchema.Implementation.builder("MCP Client", "0.3.1").build())
+				.build();
+			var initializeMessage = new McpSchema.JSONRPCRequest(McpSchema.METHOD_INITIALIZE, "test-id",
+					initializeRequest);
+			StepVerifier
+				.create(t.sendMessage(initializeMessage).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)))
+				.verifyComplete();
+
+			var testMessage = new McpSchema.JSONRPCNotification(McpSchema.METHOD_NOTIFICATION_INITIALIZED);
+
+			StepVerifier
+				.create(t.sendMessage(testMessage).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)))
+				.verifyComplete();
+
+			var requestCaptor = ArgumentCaptor.forClass(HttpRequest.Builder.class);
+			verify(mockRequestCustomizer, atLeastOnce()).customize(requestCaptor.capture(), eq("POST"), eq(uri), any(),
+					eq(context));
+			assertThat(requestCaptor.getValue().build().headers().firstValue(HttpHeaders.MCP_METHOD))
+				.hasValue(McpSchema.METHOD_NOTIFICATION_INITIALIZED);
+		});
+	}
+
+	@Test
+	void testNoMcpMethodHeaderOnResponse() throws URISyntaxException {
+		var uri = new URI(host + "/mcp");
+		var mockRequestCustomizer = mock(McpSyncHttpClientRequestCustomizer.class);
+
+		var transport = HttpClientStreamableHttpTransport.builder(host)
+			.httpRequestCustomizer(mockRequestCustomizer)
+			.build();
+
+		withTransport(transport, (t) -> {
+			var initializeRequest = McpSchema.InitializeRequest
+				.builder(ProtocolVersions.MCP_2025_11_25, McpSchema.ClientCapabilities.builder().roots(true).build(),
+						McpSchema.Implementation.builder("MCP Client", "0.3.1").build())
+				.build();
+			var initializeMessage = new McpSchema.JSONRPCRequest(McpSchema.METHOD_INITIALIZE, "test-id",
+					initializeRequest);
+			StepVerifier
+				.create(t.sendMessage(initializeMessage).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)))
+				.verifyComplete();
+
+			var testMessage = McpSchema.JSONRPCResponse.result("test-id-2", Map.of());
+
+			StepVerifier
+				.create(t.sendMessage(testMessage).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)))
+				.verifyComplete();
+
+			var requestCaptor = ArgumentCaptor.forClass(HttpRequest.Builder.class);
+			verify(mockRequestCustomizer, atLeastOnce()).customize(requestCaptor.capture(), eq("POST"), eq(uri), any(),
+					eq(context));
+			assertThat(requestCaptor.getValue().build().headers().firstValue(HttpHeaders.MCP_METHOD)).isEmpty();
+		});
+	}
+
 }