feat(transport): support Base64 sentinel header encoding for Mcp-Name and return -32020 HeaderMismatch

* Encode non-ASCII and sentinel-matching Mcp-Name values in Base64 sentinel
  format (=?base64?...?=) in HttpClientStreamableHttpTransport to prevent
  JDK HttpClient IllegalArgumentException on non-Latin-1 characters.
* Decode Base64 sentinel Mcp-Name values on HttpServletStreamableServerTransportProvider
  and HttpServletStatelessServerTransport prior to body validation.
* Add HEADER_MISMATCH (-32020) error code to McpSchema.ErrorCodes per SEP-2243
  and return it on header/body mismatches.
* Add unit and integration tests for Base64 sentinel encoding/decoding and
  -32020 mismatch error codes.

Co-authored-by: Nikita Kibitkin <nikita.n.kibitkin@gmail.com>

Author: slachiewicz

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

@@ -561,7 +561,7 @@ public Mono<Void> sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 					builder = builder.header(HttpHeaders.MCP_METHOD, jsonrpcRequest.method());
 					String name = extractNameFromParams(jsonrpcRequest.method(), jsonrpcRequest.params());
 					if (name != null) {
-						builder = builder.header(HttpHeaders.MCP_NAME, name);
+						builder = builder.header(HttpHeaders.MCP_NAME, HttpHeaders.encodeHeaderValue(name));
 					}
 				}
 				else if (sentMessage instanceof McpSchema.JSONRPCNotification jsonrpcNotification) {

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

@@ -334,7 +334,7 @@ private boolean validateMcpHeaders(HttpServletRequest request, HttpServletRespon
 		String methodHeader = request.getHeader(HttpHeaders.MCP_METHOD);
 		if (methodHeader != null && !methodHeader.isBlank() && !method.equals(methodHeader)) {
 			this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
-					McpError.builder(McpSchema.ErrorCodes.INVALID_REQUEST)
+					McpError.builder(McpSchema.ErrorCodes.HEADER_MISMATCH)
 						.message("Mcp-Method header mismatch: expected '" + method + "' but was '" + methodHeader + "'")
 						.build());
 			return false;
@@ -345,12 +345,16 @@ private boolean validateMcpHeaders(HttpServletRequest request, HttpServletRespon
 		String name = extractNameFromParams(method, params);
 		if (name != null) {
 			String nameHeader = request.getHeader(HttpHeaders.MCP_NAME);
-			if (nameHeader != null && !nameHeader.isBlank() && !name.equals(nameHeader)) {
-				this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
-						McpError.builder(McpSchema.ErrorCodes.INVALID_REQUEST)
-							.message("Mcp-Name header mismatch: expected '" + name + "' but was '" + nameHeader + "'")
-							.build());
-				return false;
+			if (nameHeader != null && !nameHeader.isBlank()) {
+				String decodedName = HttpHeaders.decodeHeaderValue(nameHeader);
+				if (!name.equals(decodedName)) {
+					this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
+							McpError.builder(McpSchema.ErrorCodes.HEADER_MISMATCH)
+								.message("Mcp-Name header mismatch: expected '" + name + "' but was '" + nameHeader
+										+ "'")
+								.build());
+					return false;
+				}
 			}
 		}
 

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

@@ -735,7 +735,7 @@ private boolean validateMcpHeaders(HttpServletRequest request, HttpServletRespon
 		String methodHeader = request.getHeader(HttpHeaders.MCP_METHOD);
 		if (methodHeader != null && !methodHeader.isBlank() && !method.equals(methodHeader)) {
 			this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
-					McpError.builder(McpSchema.ErrorCodes.INVALID_REQUEST)
+					McpError.builder(McpSchema.ErrorCodes.HEADER_MISMATCH)
 						.message("Mcp-Method header mismatch: expected '" + method + "' but was '" + methodHeader + "'")
 						.build());
 			return false;
@@ -746,12 +746,16 @@ private boolean validateMcpHeaders(HttpServletRequest request, HttpServletRespon
 		String name = extractNameFromParams(method, params);
 		if (name != null) {
 			String nameHeader = request.getHeader(HttpHeaders.MCP_NAME);
-			if (nameHeader != null && !nameHeader.isBlank() && !name.equals(nameHeader)) {
-				this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
-						McpError.builder(McpSchema.ErrorCodes.INVALID_REQUEST)
-							.message("Mcp-Name header mismatch: expected '" + name + "' but was '" + nameHeader + "'")
-							.build());
-				return false;
+			if (nameHeader != null && !nameHeader.isBlank()) {
+				String decodedName = HttpHeaders.decodeHeaderValue(nameHeader);
+				if (!name.equals(decodedName)) {
+					this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
+							McpError.builder(McpSchema.ErrorCodes.HEADER_MISMATCH)
+								.message("Mcp-Name header mismatch: expected '" + name + "' but was '" + nameHeader
+										+ "'")
+								.build());
+					return false;
+				}
 			}
 		}
 

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

@@ -73,4 +73,78 @@ public interface HttpHeaders {
 	 */
 	String CACHE_CONTROL = "Cache-Control";
 
+	/**
+	 * Prefix used for Base64 sentinel-encoded header values per SEP-2243.
+	 */
+	String BASE64_SENTINEL_PREFIX = "=?base64?";
+
+	/**
+	 * Suffix used for Base64 sentinel-encoded header values per SEP-2243.
+	 */
+	String BASE64_SENTINEL_SUFFIX = "?=";
+
+	/**
+	 * Encodes an HTTP header value per SEP-2243. If the value contains non-ASCII
+	 * characters, control characters, leading/trailing whitespace, or matches the
+	 * sentinel pattern, it is wrapped in Base64 sentinel encoding
+	 * ({@code =?base64?...?=}).
+	 * @param value the raw string value
+	 * @return the header-safe value, encoded if necessary
+	 */
+	static String encodeHeaderValue(String value) {
+		if (value == null || value.isEmpty()) {
+			return value;
+		}
+		if (requiresBase64Encoding(value)) {
+			return BASE64_SENTINEL_PREFIX
+					+ java.util.Base64.getEncoder()
+						.encodeToString(value.getBytes(java.nio.charset.StandardCharsets.UTF_8))
+					+ BASE64_SENTINEL_SUFFIX;
+		}
+		return value;
+	}
+
+	/**
+	 * Decodes an HTTP header value that may be Base64 sentinel-encoded per SEP-2243.
+	 * @param headerValue the raw header value from the HTTP request
+	 * @return the decoded string value, or the original value if not encoded or malformed
+	 */
+	static String decodeHeaderValue(String headerValue) {
+		if (headerValue == null || headerValue.isEmpty()) {
+			return headerValue;
+		}
+		if (headerValue.startsWith(BASE64_SENTINEL_PREFIX) && headerValue.endsWith(BASE64_SENTINEL_SUFFIX)) {
+			String encoded = headerValue.substring(BASE64_SENTINEL_PREFIX.length(),
+					headerValue.length() - BASE64_SENTINEL_SUFFIX.length());
+			try {
+				byte[] decoded = java.util.Base64.getDecoder().decode(encoded);
+				return new String(decoded, java.nio.charset.StandardCharsets.UTF_8);
+			}
+			catch (IllegalArgumentException ignored) {
+				return headerValue;
+			}
+		}
+		return headerValue;
+	}
+
+	private static boolean requiresBase64Encoding(String s) {
+		if (s.isEmpty()) {
+			return false;
+		}
+		if (s.charAt(0) == ' ' || s.charAt(0) == '\t' || s.charAt(s.length() - 1) == ' '
+				|| s.charAt(s.length() - 1) == '\t') {
+			return true;
+		}
+		for (int i = 0; i < s.length(); i++) {
+			char c = s.charAt(i);
+			if (c < 0x20 || c > 0x7E) {
+				return true;
+			}
+		}
+		if (s.startsWith(BASE64_SENTINEL_PREFIX) && s.endsWith(BASE64_SENTINEL_SUFFIX)) {
+			return true;
+		}
+		return false;
+	}
+
 }

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

@@ -158,6 +158,12 @@ public static final class ErrorCodes {
 		 */
 		public static final int URL_ELICITATION_REQUIRED = -32042;
 
+		/**
+		 * An MCP HTTP header (Mcp-Method, Mcp-Name, or MCP-Protocol-Version) does not
+		 * match the JSON-RPC body.
+		 */
+		public static final int HEADER_MISMATCH = -32020;
+
 	}
 
 	/**

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

@@ -133,4 +133,39 @@ void omitsMcpProtocolVersionHeaderOnInitializeRequest() throws IOException {
 		}
 	}
 
+	@Test
+	void emitsBase64EncodedMcpNameForNonAsciiToolCall() throws IOException {
+		var seenNames = new java.util.concurrent.CopyOnWriteArrayList<String>();
+		var server = HttpServer.create(new InetSocketAddress(0), 0);
+
+		try {
+			server.createContext("/mcp", exchange -> {
+				seenNames.add(exchange.getRequestHeaders().getFirst(HttpHeaders.MCP_NAME));
+				exchange.getRequestBody().readAllBytes();
+				exchange.sendResponseHeaders(202, -1);
+				exchange.close();
+			});
+			server.start();
+
+			var transport = HttpClientStreamableHttpTransport
+				.builder("http://localhost:" + server.getAddress().getPort())
+				.endpoint("/mcp")
+				.build();
+
+			try {
+				var request = new McpSchema.CallToolRequest("計算機", Map.of(), null);
+				var testMessage = new McpSchema.JSONRPCRequest(McpSchema.METHOD_TOOLS_CALL, "test-id", request);
+				StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+			}
+			finally {
+				StepVerifier.create(transport.closeGracefully()).verifyComplete();
+			}
+
+			assertThat(seenNames).contains("=?base64?6KiI566X5qmf?=");
+		}
+		finally {
+			server.stop(0);
+		}
+	}
+
 }

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

@@ -70,7 +70,7 @@ void streamableRejectsMcpMethodMismatch() throws Exception {
 		var resp = invoke(provider, "/mcp", Map.of(HttpHeaders.MCP_METHOD, "wrong/method"), toolCallBody("t"));
 
 		assertThat(resp.getStatus()).isEqualTo(400);
-		assertThat(resp.getContentAsString()).contains("Mcp-Method header mismatch");
+		assertThat(resp.getContentAsString()).contains("Mcp-Method header mismatch", "-32020");
 	}
 
 	@Test
@@ -80,7 +80,17 @@ void streamableRejectsMcpNameMismatch() throws Exception {
 		var resp = invoke(provider, "/mcp", Map.of(HttpHeaders.MCP_NAME, "wrong-name"), toolCallBody("t"));
 
 		assertThat(resp.getStatus()).isEqualTo(400);
-		assertThat(resp.getContentAsString()).contains("Mcp-Name header mismatch");
+		assertThat(resp.getContentAsString()).contains("Mcp-Name header mismatch", "-32020");
+	}
+
+	@Test
+	void streamableAcceptsBase64EncodedMcpName() throws Exception {
+		var provider = HttpServletStreamableServerTransportProvider.builder().mcpEndpoint("/mcp").build();
+
+		var resp = invoke(provider, "/mcp", Map.of(HttpHeaders.MCP_NAME, "=?base64?6KiI566X5qmf?="),
+				toolCallBody("計算機"));
+
+		assertThat(resp.getContentAsString()).doesNotContain("Mcp-Name header mismatch");
 	}
 
 	@Test
@@ -115,7 +125,7 @@ void statelessRejectsMcpMethodMismatch() throws Exception {
 		var resp = invoke(transport, "/mcp", Map.of(HttpHeaders.MCP_METHOD, "wrong/method"), toolCallBody("t"));
 
 		assertThat(resp.getStatus()).isEqualTo(400);
-		assertThat(resp.getContentAsString()).contains("Mcp-Method header mismatch");
+		assertThat(resp.getContentAsString()).contains("Mcp-Method header mismatch", "-32020");
 	}
 
 	@Test
@@ -125,7 +135,17 @@ void statelessRejectsMcpNameMismatch() throws Exception {
 		var resp = invoke(transport, "/mcp", Map.of(HttpHeaders.MCP_NAME, "wrong-name"), toolCallBody("t"));
 
 		assertThat(resp.getStatus()).isEqualTo(400);
-		assertThat(resp.getContentAsString()).contains("Mcp-Name header mismatch");
+		assertThat(resp.getContentAsString()).contains("Mcp-Name header mismatch", "-32020");
+	}
+
+	@Test
+	void statelessAcceptsBase64EncodedMcpName() throws Exception {
+		var transport = HttpServletStatelessServerTransport.builder().messageEndpoint("/mcp").build();
+
+		var resp = invoke(transport, "/mcp", Map.of(HttpHeaders.MCP_NAME, "=?base64?6KiI566X5qmf?="),
+				toolCallBody("計算機"));
+
+		assertThat(resp.getContentAsString()).doesNotContain("Mcp-Name header mismatch");
 	}
 
 	@Test