Skip to content

Commit 1d26903

Browse files
neerajbhattclaude
andcommitted
Forward Mcp-Name header in McpTransportContext
Expose the decoded Mcp-Name request header to server features through a new McpNameHeader value stored under McpNameHeader.TRANSPORT_CONTEXT_KEY. - HTTP: every validated JSON-RPC request carries a value, attached after the user's context extractor so it always wins. The value is either ABSENT, MALFORMED (bad base64, repeated values, or names differing only in case), or the decoded value. - Stdio: carries the NOT_MIRRORED sentinel, so features can tell "no headers on this transport" apart from "client omitted the header". - Decoding reuses McpHeaderDecoder and reads every header name and value through the header accessor. toString() never includes the value. The transport only decodes and forwards. For methods it does not validate itself, the feature owns the equality check against params and should treat a malformed value as a mismatch. Existing validateHeaders() behavior is unchanged. Fixes #1317 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 2d5a5bf commit 1d26903

7 files changed

Lines changed: 323 additions & 6 deletions

File tree

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
/*
2+
* Copyright 2026-2026 the original author or authors.
3+
*/
4+
5+
package io.modelcontextprotocol.modern.server;
6+
7+
import io.modelcontextprotocol.util.Assert;
8+
import reactor.util.annotation.Nullable;
9+
10+
/**
11+
* The decoded {@code Mcp-Name} header of a JSON-RPC request over HTTP, or its absence or
12+
* malformed state.
13+
* <p>
14+
* An HTTP transport decodes the header and adds it to the transport context under
15+
* {@link #TRANSPORT_CONTEXT_KEY} on every JSON-RPC request. Transports without headers
16+
* use {@link #NOT_MIRRORED} instead. The transport only decodes and forwards this value;
17+
* features whose methods the transport does not validate (for example, {@code tasks/get},
18+
* {@code tasks/update}, and {@code tasks/cancel}) must compare it against their request
19+
* parameters and treat {@link #isMalformed()} as a mismatch.
20+
* <p>
21+
* Header names are matched ignoring case. A present header either has a decoded value or
22+
* is malformed, never both.
23+
*
24+
* @author Neeraj Bhatt
25+
* @see <a href="https://modelcontextprotocol.io/seps/2243-http-standardization">SEP-2243:
26+
* HTTP Standardization</a>
27+
* @see <a href=
28+
* "https://modelcontextprotocol.io/seps/2663-tasks-extension#streamable-http-routing-headers">SEP-2663:
29+
* Streamable HTTP Routing Headers</a>
30+
*/
31+
public final class McpNameHeader {
32+
33+
/**
34+
* The transport context key under which a transport provides the {@code Mcp-Name}
35+
* header of a JSON-RPC request.
36+
*/
37+
public static final String TRANSPORT_CONTEXT_KEY = McpNameHeader.class.getName();
38+
39+
/**
40+
* Marks a transport without headers, such as stdio. Compared by identity with
41+
* {@link #ABSENT} to distinguish it from an HTTP request without the header.
42+
*/
43+
public static final McpNameHeader NOT_MIRRORED = new McpNameHeader(State.NOT_MIRRORED, null);
44+
45+
/**
46+
* Marks an HTTP request without the {@code Mcp-Name} header. Compared by identity
47+
* with {@link #NOT_MIRRORED} to distinguish the two states.
48+
*/
49+
public static final McpNameHeader ABSENT = new McpNameHeader(State.ABSENT, null);
50+
51+
/**
52+
* Marks a present header whose value was missing, could not be decoded, or was sent
53+
* more than once.
54+
*/
55+
public static final McpNameHeader MALFORMED = new McpNameHeader(State.MALFORMED, null);
56+
57+
private final State state;
58+
59+
@Nullable
60+
private final String value;
61+
62+
private McpNameHeader(State state, @Nullable String value) {
63+
this.state = state;
64+
this.value = value;
65+
}
66+
67+
/**
68+
* Creates a header holding a decoded value.
69+
* @param decodedValue the decoded {@code Mcp-Name} value, not {@code null}
70+
* @return the present header
71+
*/
72+
public static McpNameHeader of(String decodedValue) {
73+
Assert.notNull(decodedValue, "decodedValue must not be null");
74+
return new McpNameHeader(State.PRESENT, decodedValue);
75+
}
76+
77+
/**
78+
* Whether the header was sent, whether its value is valid or malformed.
79+
* @return {@code true} if the header is present
80+
*/
81+
public boolean isPresent() {
82+
return this.state == State.PRESENT || this.state == State.MALFORMED;
83+
}
84+
85+
/**
86+
* Whether the header was sent but had no valid decoded value.
87+
* @return {@code true} if the header is malformed
88+
*/
89+
public boolean isMalformed() {
90+
return this.state == State.MALFORMED;
91+
}
92+
93+
/**
94+
* The decoded value of a present, valid header.
95+
* @return the decoded value, or {@code null} if the header is absent, malformed, or
96+
* the transport has no headers
97+
*/
98+
@Nullable
99+
public String value() {
100+
return this.value;
101+
}
102+
103+
@Override
104+
public String toString() {
105+
return "McpNameHeader[" + this.state + "]";
106+
}
107+
108+
private enum State {
109+
110+
NOT_MIRRORED, ABSENT, MALFORMED, PRESENT
111+
112+
}
113+
114+
}

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
import io.modelcontextprotocol.modern.McpSchema;
2929
import io.modelcontextprotocol.modern.McpSchema.ErrorCodes;
3030
import io.modelcontextprotocol.modern.McpSchema.MetaKeys;
31+
import io.modelcontextprotocol.modern.server.McpNameHeader;
3132
import io.modelcontextprotocol.modern.server.McpParamHeaders;
3233
import io.modelcontextprotocol.modern.server.McpRequestManager;
3334
import io.modelcontextprotocol.modern.server.McpServer;
@@ -240,8 +241,11 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
240241
return;
241242
}
242243

244+
// Added after the user's extractor ran, so these entries always win.
245+
var mcpNameHeader = McpHeaderDecoder.nameHeader(headerAccessor(request));
246+
transportContext = transportContext.putAll(Map.of(McpNameHeader.TRANSPORT_CONTEXT_KEY, mcpNameHeader));
247+
243248
if (McpSchema.METHOD_TOOLS_CALL.equals(jsonRpcRequest.method())) {
244-
// Added after the user's extractor ran, so this entry always wins.
245249
var mcpParamHeaders = McpHeaderDecoder.paramHeaders(headerAccessor(request));
246250
transportContext = transportContext.putAll(Map.of(McpParamHeaders.TRANSPORT_CONTEXT_KEY, mcpParamHeaders));
247251
}

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
import java.util.Map;
1818
import java.util.Set;
1919

20+
import io.modelcontextprotocol.modern.server.McpNameHeader;
2021
import io.modelcontextprotocol.modern.server.McpParamHeaders;
2122
import io.modelcontextprotocol.server.transport.HeaderAccessor;
2223
import reactor.util.annotation.Nullable;
@@ -90,6 +91,31 @@ public static String decodeValue(String raw) {
9091
return raw;
9192
}
9293

94+
/**
95+
* Collects the {@code Mcp-Name} header, ignoring the header name's case. A repeated
96+
* header or an undecodable value is marked malformed.
97+
* @param headers the request headers
98+
* @return the decoded header, or its absent or malformed state
99+
*/
100+
public static McpNameHeader nameHeader(HeaderAccessor headers) {
101+
List<String> values = new ArrayList<>();
102+
boolean found = false;
103+
for (String name : headers.getHeaderNames()) {
104+
if ("Mcp-Name".equalsIgnoreCase(name)) {
105+
found = true;
106+
values.addAll(headers.getHeader(name));
107+
}
108+
}
109+
if (!found) {
110+
return McpNameHeader.ABSENT;
111+
}
112+
if (values.size() != 1) {
113+
return McpNameHeader.MALFORMED;
114+
}
115+
String decoded = decodeValue(values.get(0));
116+
return decoded == null ? McpNameHeader.MALFORMED : McpNameHeader.of(decoded);
117+
}
118+
93119
/**
94120
* Collects the {@code Mcp-Param-{Name}} headers of a request.
95121
* <p>

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
import io.modelcontextprotocol.modern.JsonRpc.JSONRPCResponse;
2525
import io.modelcontextprotocol.modern.JsonRpc.JSONRPCResponse.JSONRPCError;
2626
import io.modelcontextprotocol.modern.McpSchema;
27+
import io.modelcontextprotocol.modern.server.McpNameHeader;
2728
import io.modelcontextprotocol.modern.server.McpParamHeaders;
2829
import io.modelcontextprotocol.modern.server.McpRequestManager;
2930
import io.modelcontextprotocol.modern.server.McpTransportResponse;
@@ -51,10 +52,10 @@ public class StdioMcpTransport {
5152

5253
private static final int DEFAULT_INPUT_MAX_SIZE = 16 * 1024 * 1024;
5354

54-
// Stdio has no headers, so Mcp-Param-* headers are never mirrored and the tools
55-
// feature skips their validation.
55+
// Stdio has no headers, so mirrored header validation is skipped.
5656
private static final McpTransportContext TRANSPORT_CONTEXT = McpTransportContext
57-
.create(Map.of(McpParamHeaders.TRANSPORT_CONTEXT_KEY, McpParamHeaders.NOT_MIRRORED));
57+
.create(Map.of(McpParamHeaders.TRANSPORT_CONTEXT_KEY, McpParamHeaders.NOT_MIRRORED,
58+
McpNameHeader.TRANSPORT_CONTEXT_KEY, McpNameHeader.NOT_MIRRORED));
5859

5960
private final McpRequestManager requestManager;
6061

‎mcp-core/src/test/java/io/modelcontextprotocol/modern/server/transport/McpHeaderDecoderTests.java‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
import java.util.List;
1010
import java.util.Map;
1111

12+
import io.modelcontextprotocol.modern.server.McpNameHeader;
1213
import io.modelcontextprotocol.modern.server.McpParamHeaders;
1314
import io.modelcontextprotocol.server.transport.HeaderAccessor;
1415
import org.junit.jupiter.api.Test;
@@ -87,6 +88,89 @@ void plainValueWithCharactersOutsideVisibleAsciiSpaceAndTabIsMalformed(String ra
8788
assertThat(McpHeaderDecoder.decodeValue(raw)).isNull();
8889
}
8990

91+
@Test
92+
void nameHeaderIsAbsentWhenMissing() {
93+
McpNameHeader header = McpHeaderDecoder.nameHeader(headers("Mcp-Method", "tools/call"));
94+
95+
assertThat(header).isSameAs(McpNameHeader.ABSENT);
96+
assertThat(header.isPresent()).isFalse();
97+
assertThat(header.value()).isNull();
98+
}
99+
100+
@Test
101+
void nameHeaderWithNoValuesIsMalformed() {
102+
HeaderAccessor emptyValue = new HeaderAccessor() {
103+
@Override
104+
public List<String> getHeader(String name) {
105+
return List.of();
106+
}
107+
108+
@Override
109+
public List<String> getHeaderNames() {
110+
return List.of("Mcp-Name");
111+
}
112+
};
113+
114+
assertThat(McpHeaderDecoder.nameHeader(emptyValue)).isSameAs(McpNameHeader.MALFORMED);
115+
}
116+
117+
@Test
118+
void nameHeaderIsReadIgnoringCase() {
119+
McpNameHeader header = McpHeaderDecoder.nameHeader(headers("mCP-NaMe", "private-name"));
120+
121+
assertThat(header.isPresent()).isTrue();
122+
assertThat(header.isMalformed()).isFalse();
123+
assertThat(header.value()).isEqualTo("private-name");
124+
assertThat(header.toString()).doesNotContain("private-name");
125+
}
126+
127+
@Test
128+
void nameHeaderValueIsDecoded() {
129+
McpNameHeader header = McpHeaderDecoder.nameHeader(headers("Mcp-Name", "=?base64?SGVsbG8=?="));
130+
131+
assertThat(header.value()).isEqualTo("Hello");
132+
}
133+
134+
@Test
135+
void malformedNameHeaderValueIsMarkedMalformed() {
136+
McpNameHeader header = McpHeaderDecoder.nameHeader(headers("Mcp-Name", "=?base64?SGVsbG8?="));
137+
138+
assertThat(header).isSameAs(McpNameHeader.MALFORMED);
139+
assertThat(header.isPresent()).isTrue();
140+
assertThat(header.value()).isNull();
141+
}
142+
143+
@Test
144+
void nameHeaderWithSeveralValuesIsMarkedMalformed() {
145+
McpNameHeader header = McpHeaderDecoder.nameHeader(headers("Mcp-Name", "one", "Mcp-Name", "two"));
146+
147+
assertThat(header).isSameAs(McpNameHeader.MALFORMED);
148+
}
149+
150+
@Test
151+
void nameHeadersDifferingOnlyInCaseAreMarkedMalformed() {
152+
Map<String, List<String>> values = Map.of("Mcp-Name", List.of("one"), "mcp-name", List.of("two"));
153+
HeaderAccessor caseSensitive = new HeaderAccessor() {
154+
@Override
155+
public List<String> getHeader(String name) {
156+
return values.getOrDefault(name, List.of());
157+
}
158+
159+
@Override
160+
public List<String> getHeaderNames() {
161+
return List.copyOf(values.keySet());
162+
}
163+
};
164+
165+
assertThat(McpHeaderDecoder.nameHeader(caseSensitive)).isSameAs(McpNameHeader.MALFORMED);
166+
}
167+
168+
@Test
169+
void notMirroredNameHeaderIsDistinctFromAbsent() {
170+
assertThat(McpNameHeader.NOT_MIRRORED).isNotSameAs(McpNameHeader.ABSENT);
171+
assertThat(McpNameHeader.NOT_MIRRORED.isPresent()).isFalse();
172+
}
173+
90174
@Test
91175
void paramHeadersSelectsMcpParamHeadersIgnoringThePrefixCase() {
92176
McpParamHeaders headers = McpHeaderDecoder.paramHeaders(headers("Mcp-Param-Region", "eu", "MCP-PARAM-Tenant",

0 commit comments

Comments
 (0)