Forward Mcp-Name header in McpTransportContext -> McpHeaders

- Fixes #1317

Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>

Author: Kehrlann

mcp-core/src/main/java/io/modelcontextprotocol/modern/server/McpHeader.java

@@ -50,7 +50,8 @@ public static McpHeader malformed(String name) {
 	}
 
 	/**
-	 * The header name, in the case it was received.
+	 * The header name, such as {@code Mcp-Name} or {@code Mcp-Param-Region}. Header names
+	 * are case-insensitive, so compare it ignoring case.
 	 * @return the header name
 	 */
 	public String name() {

mcp-core/src/main/java/io/modelcontextprotocol/modern/server/McpHeaders.java

@@ -9,19 +9,26 @@
 import java.util.Locale;
 import java.util.Map;
 
+import io.modelcontextprotocol.modern.McpHttp.Headers;
 import io.modelcontextprotocol.util.Assert;
 import org.jspecify.annotations.Nullable;
 
 /**
- * The request headers a client mirrors from the JSON-RPC body: the
- * {@code Mcp-Param-{Name}} headers of a {@code tools/call} request, which mirror the
- * arguments a tool annotates with {@code x-mcp-header}.
+ * The request headers a client mirrors from the JSON-RPC body:
+ * <ul>
+ * <li>{@code Mcp-Name}, which mirrors the tool or prompt name or the resource URI, and
+ * for methods defined outside the core specification, such as {@code tasks/get}, the
+ * parameter that method designates;</li>
+ * <li>the {@code Mcp-Param-{Name}} headers of a {@code tools/call} request, which mirror
+ * the arguments a tool annotates with {@code x-mcp-header}.</li>
+ * </ul>
  * <p>
  * An HTTP transport decodes the headers, for instance with
- * {@code McpHeaderDecoder.paramHeaders}, and adds them to the transport context under
- * {@link #TRANSPORT_CONTEXT_KEY}. A transport that has no headers, such as stdio, maps
- * the key to {@link #NOT_MIRRORED} instead. The tools feature validates the headers
- * against the arguments, and fails the call as an internal error when the key is missing.
+ * {@code McpHeaderDecoder.headers}, and adds them to the transport context of every
+ * request under {@link #TRANSPORT_CONTEXT_KEY}. A transport that has no headers, such as
+ * stdio, maps the key to {@link #NOT_MIRRORED} instead. The tools feature validates the
+ * {@code Mcp-Param-{Name}} headers against the arguments, and fails the call as an
+ * internal error when the key is missing.
  * <p>
  * Headers are looked up ignoring case.
  *
@@ -37,11 +44,6 @@ public final class McpHeaders {
 	 */
 	public static final String TRANSPORT_CONTEXT_KEY = McpHeaders.class.getName();
 
-	/**
-	 * The prefix of every {@code Mcp-Param-{Name}} header name.
-	 */
-	public static final String PARAM_PREFIX = "Mcp-Param-";
-
 	/**
 	 * Marks a transport that never mirrors the body into headers, such as stdio, so
 	 * header validation is skipped. Compared by identity: headers built with
@@ -82,7 +84,7 @@ public static Builder builder() {
 
 	private static String paramHeaderName(String name) {
 		Assert.notNull(name, "name must not be null");
-		return PARAM_PREFIX + name;
+		return Headers.MCP_PARAM_PREFIX + name;
 	}
 
 	private static String normalize(String headerName) {
@@ -102,17 +104,32 @@ private Builder() {
 		}
 
 		/**
-		 * Adds an {@code Mcp-Param-{Name}} header. A name added more than once, ignoring
-		 * case, is malformed, because a header sent more than once has no single value to
-		 * compare.
-		 * @param name the {@code {Name}} part of {@code Mcp-Param-{Name}}, in any case
+		 * Adds a header by its full name, such as {@code Mcp-Name}. A header added more
+		 * than once, ignoring case, is malformed, because a header sent more than once
+		 * has no single value to compare. The name is not checked: callers are expected
+		 * to add only the headers a client mirrors from the body.
+		 * @param name the full name of the header, in any case
+		 * @param value the decoded value, or {@code null} if the header was sent but
+		 * couldn't be decoded
+		 * @return this builder
+		 */
+		public Builder header(String name, @Nullable String value) {
+			var header = (value != null) ? McpHeader.of(name, value) : McpHeader.malformed(name);
+			return add(header);
+		}
+
+		/**
+		 * Adds an {@code Mcp-Param-{Name}} header. A paramName added more than once,
+		 * ignoring case, is malformed, because a header sent more than once has no single
+		 * value to compare.
+		 * @param paramName the {@code {Name}} part of {@code Mcp-Param-{Name}}, in any
+		 * case
 		 * @param value the decoded value, or {@code null} if the header was sent but
 		 * couldn't be decoded
 		 * @return this builder
 		 */
-		public Builder param(String name, @Nullable String value) {
-			String headerName = paramHeaderName(name);
-			return add((value != null) ? McpHeader.of(headerName, value) : McpHeader.malformed(headerName));
+		public Builder paramHeader(String paramName, @Nullable String value) {
+			return header(paramHeaderName(paramName), value);
 		}
 
 		// A header added again, ignoring case, becomes malformed and keeps the name it

mcp-core/src/main/java/io/modelcontextprotocol/modern/server/McpRequestManager.java

@@ -14,9 +14,11 @@
  * {@link McpTransportResponse}. Use {@link #handleBlocking} when the calling thread may
  * block, {@link #handle} when it must not. Neither completes with an error.
  * <p>
- * For {@code tools/call}, the transport context must map
- * {@link McpHeaders#TRANSPORT_CONTEXT_KEY} to the request's {@code Mcp-Param-{Name}}
- * headers, or to {@link McpHeaders#NOT_MIRRORED} for a transport without headers.
+ * For every request, the transport context must map
+ * {@link McpHeaders#TRANSPORT_CONTEXT_KEY} to the request's mirrored headers
+ * ({@code Mcp-Name} and {@code Mcp-Param-{Name}}), or to {@link McpHeaders#NOT_MIRRORED}
+ * for a transport without headers. Features read them to check the headers against the
+ * body, for instance the tools feature for {@code tools/call}.
  *
  * @author Dariusz Jędrzejczyk
  */

mcp-core/src/main/java/io/modelcontextprotocol/modern/server/feature/ParamHeaderValidator.java

@@ -10,6 +10,7 @@
 import java.util.Map;
 import java.util.regex.Pattern;
 
+import io.modelcontextprotocol.modern.McpHttp.Headers;
 import io.modelcontextprotocol.modern.ToolParamHeaderAnnotations.Annotation;
 import io.modelcontextprotocol.modern.ToolParamHeaderAnnotations.Type;
 import io.modelcontextprotocol.modern.server.McpHeader;
@@ -126,7 +127,7 @@ private static BigDecimal decimal(Number number) {
 	}
 
 	private static String header(Annotation annotation) {
-		return McpHeaders.PARAM_PREFIX + annotation.name();
+		return Headers.MCP_PARAM_PREFIX + annotation.name();
 	}
 
 	private static String describe(McpHeaders headers, String name) {

mcp-core/src/main/java/io/modelcontextprotocol/modern/server/feature/ToolsFeature.java

@@ -153,16 +153,15 @@ private static void validateParamHeaders(McpRequestContext ctx, Tool tool, Map<S
 		}
 		// Failing rather than skipping, so a transport that forgets the headers can't
 		// silently disable validation.
-		if (!(headers instanceof McpHeaders paramHeaders)) {
+		if (!(headers instanceof McpHeaders mcpHeaders)) {
 			logger.warn(
 					"Cannot validate Mcp-Param headers for tool '{}': transport context key '{}' is {}. The transport "
 							+ "must map it to an McpHeaders, or to McpHeaders.NOT_MIRRORED if it has no headers",
 					tool.name(), McpHeaders.TRANSPORT_CONTEXT_KEY,
 					(headers == null) ? "missing" : "a " + headers.getClass().getName());
 			throw new McpException(ErrorCodes.INTERNAL_ERROR, "Internal error");
 		}
-		ParamHeaderValidator.Result result = ParamHeaderValidator.validate(annotations.valid(), arguments,
-				paramHeaders);
+		ParamHeaderValidator.Result result = ParamHeaderValidator.validate(annotations.valid(), arguments, mcpHeaders);
 		if (result instanceof ParamHeaderValidator.Invalid invalid) {
 			throw new McpException(ErrorCodes.HEADER_MISMATCH, invalid.problem());
 		}

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

@@ -248,11 +248,10 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 			return;
 		}
 
-		if (McpSchema.METHOD_TOOLS_CALL.equals(jsonRpcRequest.method())) {
-			// Added after the user's extractor ran, so this entry always wins.
-			var mcpParamHeaders = McpHeaderDecoder.paramHeaders(headerAccessor(request));
-			transportContext = transportContext.putAll(Map.of(McpHeaders.TRANSPORT_CONTEXT_KEY, mcpParamHeaders));
-		}
+		// Extract headers on every request, because extensions may mirror a parameter
+		// into Mcp-Name. Added after the user's extractor ran, so this entry always wins.
+		var mcpHeaders = McpHeaderDecoder.headers(headerAccessor(request));
+		transportContext = transportContext.putAll(Map.of(McpHeaders.TRANSPORT_CONTEXT_KEY, mcpHeaders));
 
 		boolean listen = McpSchema.METHOD_SUBSCRIPTIONS_LISTEN.equals(jsonRpcRequest.method());
 		McpTransportResponse transportResponse = (listen ? this.requestManager.handle(transportContext, jsonRpcRequest)

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

@@ -88,37 +88,47 @@ private McpHeaderDecoder() {
 	}
 
 	/**
-	 * Collects the {@code Mcp-Param-{Name}} headers of a request.
+	 * Collects the {@code Mcp-Name} and {@code Mcp-Param-{Name}} headers of a request.
 	 * <p>
-	 * Headers are selected by their {@code Mcp-Param-} prefix, ignoring case. A name that
-	 * carries more than one value, including names that differ only in case, is
+	 * {@code Mcp-Name} is selected by its exact name and {@code Mcp-Param-{Name}} by its
+	 * prefix, both ignoring case, so {@code Mcp-Param-Mcp-Name} is a param header. A name
+	 * that carries more than one value, including names that differ only in case, is
 	 * malformed. Every other value is decoded with {@link #decodeValue(String)}, and
 	 * marked malformed when it can't be decoded. Rejecting a malformed header is left to
-	 * the tools feature, because only a header that the called tool declares may cause a
+	 * whoever compares it with the body: the transport for the methods it validates, and
+	 * the feature handling the method otherwise. For instance, only a
+	 * {@code Mcp-Param-{Name}} header that the called tool declares may cause a
 	 * rejection.
 	 * <p>
 	 * As with {@link #decodeValue(String)}, the accessor must return values with their
 	 * leading and trailing whitespace already removed.
 	 * @param headers the request headers
 	 * @return the decoded headers
 	 */
-	public static McpHeaders paramHeaders(HeaderAccessor headers) {
+	public static McpHeaders headers(HeaderAccessor headers) {
 		// The accessor may be case-sensitive, so values are gathered under every name
 		// that differs only in case.
 		Map<String, Set<String>> names = new LinkedHashMap<>();
 		for (String name : headers.getHeaderNames()) {
-			if (name.regionMatches(true, 0, McpHeaders.PARAM_PREFIX, 0, McpHeaders.PARAM_PREFIX.length())) {
+			if (name.equalsIgnoreCase(Headers.MCP_NAME)
+					|| name.regionMatches(true, 0, Headers.MCP_PARAM_PREFIX, 0, Headers.MCP_PARAM_PREFIX.length())) {
 				names.computeIfAbsent(name.toLowerCase(Locale.ROOT), k -> new LinkedHashSet<>()).add(name);
 			}
 		}
 		McpHeaders.Builder builder = McpHeaders.builder();
 		for (Set<String> variants : names.values()) {
-			String paramName = variants.iterator().next().substring(McpHeaders.PARAM_PREFIX.length());
 			List<String> values = new ArrayList<>();
 			for (String name : variants) {
 				values.addAll(headers.getHeader(name));
 			}
-			builder.param(paramName, values.size() == 1 ? decodeValue(values.get(0)) : null);
+			String decoded = values.size() == 1 ? decodeValue(values.get(0)) : null;
+			String headerName = variants.iterator().next();
+			if (headerName.equalsIgnoreCase(Headers.MCP_NAME)) {
+				builder.header(Headers.MCP_NAME, decoded);
+			}
+			else {
+				builder.paramHeader(headerName.substring(Headers.MCP_PARAM_PREFIX.length()), decoded);
+			}
 		}
 		return builder.build();
 	}

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

@@ -50,8 +50,8 @@ public class StdioMcpTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(StdioMcpTransport.class);
 
-	// Stdio has no headers, so Mcp-Param-* headers are never mirrored and the tools
-	// feature skips their validation.
+	// Stdio has no headers, so nothing is mirrored (neither Mcp-Name nor Mcp-Param-*)
+	// and features skip header validation.
 	private static final McpTransportContext TRANSPORT_CONTEXT = McpTransportContext
 		.create(Map.of(McpHeaders.TRANSPORT_CONTEXT_KEY, McpHeaders.NOT_MIRRORED));
 

mcp-core/src/test/java/io/modelcontextprotocol/modern/server/McpHeadersTests.java

@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.modern.server;
 
+import io.modelcontextprotocol.modern.McpHttp;
 import org.junit.jupiter.api.Test;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -12,28 +13,28 @@ class McpHeadersTests {
 
 	@Test
 	void paramAddedTwiceIgnoringCaseIsMalformed() {
-		McpHeaders headers = McpHeaders.builder().param("Region", "eu").param("region", "eu").build();
+		McpHeaders headers = McpHeaders.builder().paramHeader("Region", "eu").paramHeader("region", "eu").build();
 
 		assertThat(headers.param("region")).isEqualTo(McpHeader.malformed("Mcp-Param-Region"));
 	}
 
 	@Test
 	void paramAddedAfterNullStaysMalformed() {
-		McpHeaders headers = McpHeaders.builder().param("Region", null).param("region", "eu").build();
+		McpHeaders headers = McpHeaders.builder().paramHeader("Region", null).paramHeader("region", "eu").build();
 
 		assertThat(headers.param("region").isMalformed()).isTrue();
 	}
 
 	@Test
 	void nullParamAddedAfterValueMakesItMalformed() {
-		McpHeaders headers = McpHeaders.builder().param("Region", "eu").param("region", null).build();
+		McpHeaders headers = McpHeaders.builder().paramHeader("Region", "eu").paramHeader("region", null).build();
 
 		assertThat(headers.param("region").isMalformed()).isTrue();
 	}
 
 	@Test
 	void presentParamHasItsValue() {
-		McpHeaders headers = McpHeaders.builder().param("Region", "eu").build();
+		McpHeaders headers = McpHeaders.builder().paramHeader("Region", "eu").build();
 
 		McpHeader header = headers.param("region");
 		assertThat(header.name()).isEqualTo("Mcp-Param-Region");
@@ -43,21 +44,21 @@ void presentParamHasItsValue() {
 
 	@Test
 	void paramIsLookedUpIgnoringCase() {
-		McpHeaders headers = McpHeaders.builder().param("Region", "eu").build();
+		McpHeaders headers = McpHeaders.builder().paramHeader("Region", "eu").build();
 
 		assertThat(headers.param("REGION")).isEqualTo(headers.param("region"));
 	}
 
 	@Test
 	void absentParamIsNull() {
-		McpHeaders headers = McpHeaders.builder().param("Region", "eu").build();
+		McpHeaders headers = McpHeaders.builder().paramHeader("Region", "eu").build();
 
 		assertThat(headers.param("tenant")).isNull();
 	}
 
 	@Test
 	void paramIsLookedUpByFullHeaderNameIgnoringCase() {
-		McpHeaders headers = McpHeaders.builder().param("Region", "eu").build();
+		McpHeaders headers = McpHeaders.builder().paramHeader("Region", "eu").build();
 
 		assertThat(headers.get("mcp-param-REGION")).isEqualTo(McpHeader.of("Mcp-Param-Region", "eu"));
 		assertThat(headers.get("Region")).isNull();
@@ -67,17 +68,56 @@ void paramIsLookedUpByFullHeaderNameIgnoringCase() {
 	void paramNamedLikeAnotherMcpHeaderKeepsItsPrefix() {
 		// "Mcp-Name" is a valid x-mcp-header name, so a tool can make the client send
 		// Mcp-Param-Mcp-Name, which is not the Mcp-Name header.
-		McpHeaders headers = McpHeaders.builder().param("Mcp-Name", "echo").build();
+		McpHeaders headers = McpHeaders.builder().paramHeader("Mcp-Name", "echo").build();
 
 		assertThat(headers.get("Mcp-Param-Mcp-Name")).isEqualTo(McpHeader.of("Mcp-Param-Mcp-Name", "echo"));
 		assertThat(headers.get("Mcp-Name")).isNull();
+		assertThat(headers.get(McpHttp.Headers.MCP_NAME)).isNull();
 	}
 
 	@Test
-	void toStringOmitsValues() {
-		McpHeaders headers = McpHeaders.builder().param("Region", "eu-west1").param("Tenant", null).build();
+	void nameIsLookedUpAsMcpName() {
+		McpHeaders headers = McpHeaders.builder().header(McpHttp.Headers.MCP_NAME, "echo").build();
+
+		assertThat(headers.get(McpHttp.Headers.MCP_NAME)).isEqualTo(McpHeader.of("Mcp-Name", "echo"));
+		assertThat(headers.get("mcp-name")).isEqualTo(headers.get(McpHttp.Headers.MCP_NAME));
+		assertThat(headers.param("Name")).isNull();
+	}
+
+	@Test
+	void nameAddedTwiceIsMalformed() {
+		McpHeaders headers = McpHeaders.builder()
+			.header(McpHttp.Headers.MCP_NAME, "echo")
+			.header(McpHttp.Headers.MCP_NAME, "echo")
+			.build();
+
+		assertThat(headers.get(McpHttp.Headers.MCP_NAME)).isEqualTo(McpHeader.malformed("Mcp-Name"));
+	}
+
+	@Test
+	void nullNameIsMalformed() {
+		McpHeaders headers = McpHeaders.builder().header(McpHttp.Headers.MCP_NAME, null).build();
 
-		assertThat(headers.toString()).contains("Mcp-Param-Region", "Mcp-Param-Tenant").doesNotContain("eu-west1");
+		assertThat(headers.get(McpHttp.Headers.MCP_NAME).isMalformed()).isTrue();
+	}
+
+	@Test
+	void absentNameIsNull() {
+		McpHeaders headers = McpHeaders.builder().paramHeader("Region", "eu").build();
+
+		assertThat(headers.get(McpHttp.Headers.MCP_NAME)).isNull();
+	}
+
+	@Test
+	void toStringOmitsValues() {
+		McpHeaders headers = McpHeaders.builder()
+			.header(McpHttp.Headers.MCP_NAME, "secret-task")
+			.paramHeader("Region", "eu-west1")
+			.paramHeader("Tenant", null)
+			.build();
+
+		assertThat(headers.toString()).contains("Mcp-Name", "Mcp-Param-Region", "Mcp-Param-Tenant")
+			.doesNotContain("secret-task", "eu-west1");
 		assertThat(headers.param("region").toString()).doesNotContain("eu-west1");
 	}