Skip to content

Commit 13ac02c

Browse files
committed
Reject initialize requests with UnsupportedProtocolVersion
Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>
1 parent 66a7f61 commit 13ac02c

6 files changed

Lines changed: 199 additions & 0 deletions

File tree

‎mcp-core/src/main/java/io/modelcontextprotocol/modern/McpSchema.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,15 @@ private McpSchema() {
5353

5454
public static final String METHOD_SERVER_DISCOVER = "server/discover";
5555

56+
/**
57+
* The handshake that opens a connection in the initialization-based (legacy) protocol
58+
* versions.
59+
* @deprecated This is only used to recognize legacy client requests so they can be
60+
* rejected with an appropriate error message.
61+
*/
62+
@Deprecated
63+
public static final String METHOD_INITIALIZE = "initialize";
64+
5665
public static final String METHOD_TOOLS_LIST = "tools/list";
5766

5867
public static final String METHOD_TOOLS_CALL = "tools/call";

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,14 @@ private Mono<McpTransportResponse> dispatch(McpTransportContext transportContext
133133
return invalidParams(id, "params is malformed");
134134
}
135135
Map<String, Object> meta = asMetaMap(paramsMap.get("_meta"));
136+
if (McpSchema.METHOD_INITIALIZE.equals(request.method()) && !hasModernVersionClaim(meta)) {
137+
// Legacy client: tries to initialize and doesn't pass version header. We
138+
// reject early to return the correct error and not a header-validation error.
139+
// If there is a modern version header, it's an invalid INITIALIZE request
140+
// from a modern client: let it fall through, it will be rejected with
141+
// METHOD_NOT_FOUND
142+
return rejectLegacyInitialize(id, paramsMap);
143+
}
136144
if (meta == null) {
137145
return invalidParams(id, "params._meta is required");
138146
}
@@ -308,6 +316,40 @@ private static JSONRPCResponse bug(McpRequestContext ctx, String problem) {
308316
return JSONRPCResponse.error(ctx.requestId(), new JSONRPCError(ErrorCodes.INTERNAL_ERROR, "Internal error"));
309317
}
310318

319+
/**
320+
* Answers the {@code initialize} handshake of a client on an initialization-based
321+
* (legacy) protocol version. The server broadcasts to name its supported version(s)
322+
* in the error response.
323+
* <p>
324+
* This runs before any {@code params}/{@code _meta} validation: a legacy
325+
* {@code initialize} carries neither, and would otherwise be answered with an error
326+
* about the missing {@code _meta} instead.
327+
*
328+
* @see <a href=
329+
* "https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning#protocol-version-negotiation">Protocol
330+
* Version Negotiation</a>
331+
*/
332+
private Mono<McpTransportResponse> rejectLegacyInitialize(Object id, Map<String, Object> params) {
333+
// The legacy handshake names the client's version in params.protocolVersion. When
334+
// it is missing, "requested" is sent as an empty string: the schema requires the
335+
// field, and an empty value doesn't pretend the client asked for any version.
336+
String requested = params.get("protocolVersion") instanceof String version ? version : "";
337+
String message = "Unsupported protocol version" + (requested.isEmpty() ? "" : " " + requested)
338+
+ ": this server does not support the initialize handshake; supported protocol versions: "
339+
+ String.join(", ", this.supportedVersions);
340+
return error(id, new JSONRPCError(ErrorCodes.UNSUPPORTED_PROTOCOL_VERSION, message,
341+
new UnsupportedProtocolVersionData(this.supportedVersions, requested)));
342+
}
343+
344+
/**
345+
* Whether {@code params._meta} names a protocol version, i.e. the request claims to
346+
* follow a per-request-metadata revision rather than the legacy handshake.
347+
*/
348+
private static boolean hasModernVersionClaim(Map<String, Object> meta) {
349+
return meta != null && meta.get(MetaKeys.PROTOCOL_VERSION) instanceof String protocolVersion
350+
&& !protocolVersion.isBlank();
351+
}
352+
311353
private static Mono<McpTransportResponse> error(Object id, JSONRPCError error) {
312354
return Mono.just(McpTransportResponse.error(JSONRPCResponse.error(id, error)));
313355
}

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -413,6 +413,18 @@ private void writeJson(HttpServletResponse response, int status, JSONRPCResponse
413413
* consistent with the body
414414
*/
415415
private String validateHeaders(HttpServletRequest request, JSONRPCRequest jsonRpcRequest) {
416+
String metaVersion = protocolVersionFromMeta(jsonRpcRequest.params());
417+
if (McpSchema.METHOD_INITIALIZE.equals(jsonRpcRequest.method())
418+
&& (metaVersion == null || metaVersion.isBlank())) {
419+
// A client on an initialization-based (legacy) version opens with initialize
420+
// and sends none of these headers. Its request is left to the request
421+
// manager, which knows the supported versions and names them in its
422+
// rejection: answering "Missing required header" would leave that client with
423+
// nothing actionable. Fall through to the server validation. A blank _meta
424+
// version names no revision, so McpServer treats it as legacy too; it must be
425+
// waived here as well, or it would fail on the headers first.
426+
return null;
427+
}
416428
List<String> methodHeaders = Collections.list(request.getHeaders(Headers.MCP_METHOD));
417429
if (methodHeaders.isEmpty()) {
418430
return "Missing required header: Mcp-Method";

‎mcp-test/src/test/java/io/modelcontextprotocol/modern/server/McpServerTests.java‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,58 @@ void unsupportedVersionWinsOverMissingClientCapabilities() {
108108
.verifyComplete();
109109
}
110110

111+
@Test
112+
void legacyInitializeNamesSupportedVersions() {
113+
McpServer server = baseBuilder().supportedVersions(List.of("2026-07-28", "2026-12-01")).build();
114+
Map<String, Object> params = Map.of("protocolVersion", "2025-11-25", "capabilities", Map.of(), "clientInfo",
115+
Map.of("name", "legacy-client", "version", "1.0.0"));
116+
117+
JSONRPCResponse response = respond(server, new JSONRPCRequest("initialize", 1, params)).block();
118+
119+
JSONRPCError error = response.error();
120+
assertThat(error.code()).isEqualTo(ErrorCodes.UNSUPPORTED_PROTOCOL_VERSION);
121+
assertThat(error.message()).contains("2025-11-25", "2026-07-28, 2026-12-01");
122+
assertThat(error.data())
123+
.isEqualTo(new McpSchema.UnsupportedProtocolVersionData(List.of("2026-07-28", "2026-12-01"), "2025-11-25"));
124+
}
125+
126+
@Test
127+
void legacyInitializeWithoutProtocolVersionNamesSupportedVersions() {
128+
McpServer server = baseBuilder().build();
129+
130+
JSONRPCResponse response = respond(server, new JSONRPCRequest("initialize", 1, Map.of())).block();
131+
132+
JSONRPCError error = response.error();
133+
assertThat(error.code()).isEqualTo(ErrorCodes.UNSUPPORTED_PROTOCOL_VERSION);
134+
assertThat(error.message()).isEqualTo(
135+
"Unsupported protocol version: this server does not support the initialize handshake; supported protocol versions: "
136+
+ McpSchema.LATEST_PROTOCOL_VERSION);
137+
assertThat(error.data())
138+
.isEqualTo(new McpSchema.UnsupportedProtocolVersionData(List.of(McpSchema.LATEST_PROTOCOL_VERSION), ""));
139+
}
140+
141+
@Test
142+
void initializeWithBlankMetaVersionIsTreatedAsLegacy() {
143+
McpServer server = baseBuilder().build();
144+
145+
JSONRPCResponse response = respond(server, request("initialize", meta(MetaKeys.PROTOCOL_VERSION, ""))).block();
146+
147+
JSONRPCError error = response.error();
148+
assertThat(error.code()).isEqualTo(ErrorCodes.UNSUPPORTED_PROTOCOL_VERSION);
149+
assertThat(error.message()).contains(McpSchema.LATEST_PROTOCOL_VERSION);
150+
assertThat(error.data())
151+
.isEqualTo(new McpSchema.UnsupportedProtocolVersionData(List.of(McpSchema.LATEST_PROTOCOL_VERSION), ""));
152+
}
153+
154+
@Test
155+
void initializeWithModernMetaIsMethodNotFound() {
156+
McpServer server = baseBuilder().build();
157+
158+
StepVerifier.create(invoke(server, request("initialize", meta())))
159+
.assertNext(invocation -> assertError(invocation, ErrorCodes.METHOD_NOT_FOUND))
160+
.verifyComplete();
161+
}
162+
111163
@Test
112164
void malformedClientCapabilitiesIsInvalidParams() {
113165
McpServer server = baseBuilder().feature(echoFeature("tools/call")).build();

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -402,6 +402,64 @@ void getIsRejected() throws Exception {
402402
assertThat(response.statusCode()).isEqualTo(405);
403403
}
404404

405+
@Test
406+
void legacyInitializeIsAnsweredWithSupportedVersions() throws Exception {
407+
// What a 2025-era Streamable HTTP client sends: no Mcp-* headers, no _meta.
408+
HttpRequest request = HttpRequest.newBuilder()
409+
.uri(URI.create("http://localhost:" + PORT + ENDPOINT))
410+
.header("Content-Type", "application/json")
411+
.header("Accept", "application/json, text/event-stream")
412+
.POST(HttpRequest.BodyPublishers.ofString("""
413+
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25",\
414+
"capabilities":{},"clientInfo":{"name":"legacy-client","version":"1.0.0"}}}"""))
415+
.build();
416+
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
417+
418+
assertThat(response.statusCode()).isEqualTo(400);
419+
assertThatJson(response.body()).inPath("$.error.code").isEqualTo(ErrorCodes.UNSUPPORTED_PROTOCOL_VERSION);
420+
assertThatJson(response.body()).inPath("$.error.message")
421+
.asString()
422+
.contains(McpSchema.LATEST_PROTOCOL_VERSION);
423+
assertThatJson(response.body()).inPath("$.error.data").isEqualTo("""
424+
{"supported": ["%s"], "requested": "2025-11-25"}""".formatted(McpSchema.LATEST_PROTOCOL_VERSION));
425+
}
426+
427+
@Test
428+
void initializeWithBlankMetaVersionIsAnsweredWithSupportedVersions() throws Exception {
429+
// A blank _meta version names no revision: no header is required, and the server
430+
// rejects it like a legacy initialize.
431+
HttpRequest request = HttpRequest.newBuilder()
432+
.uri(URI.create("http://localhost:" + PORT + ENDPOINT))
433+
.header("Content-Type", "application/json")
434+
.header("Accept", "application/json, text/event-stream")
435+
.POST(HttpRequest.BodyPublishers.ofString("""
436+
{"jsonrpc":"2.0","id":1,"method":"initialize",\
437+
"params":{"_meta":{"io.modelcontextprotocol/protocolVersion":""}}}"""))
438+
.build();
439+
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
440+
441+
assertThat(response.statusCode()).isEqualTo(400);
442+
assertThatJson(response.body()).inPath("$.error.code").isEqualTo(ErrorCodes.UNSUPPORTED_PROTOCOL_VERSION);
443+
assertThatJson(response.body()).inPath("$.error.data").isEqualTo("""
444+
{"supported": ["%s"], "requested": ""}""".formatted(McpSchema.LATEST_PROTOCOL_VERSION));
445+
}
446+
447+
@Test
448+
void initializeWithModernMetaStillRequiresHeaders() throws Exception {
449+
Map<String, Object> body = Map.of("jsonrpc", "2.0", "id", 1, "method", "initialize", "params",
450+
Map.of("_meta", meta()));
451+
HttpRequest request = HttpRequest.newBuilder()
452+
.uri(URI.create("http://localhost:" + PORT + ENDPOINT))
453+
.header("Content-Type", "application/json")
454+
.header("Accept", "application/json, text/event-stream")
455+
.POST(HttpRequest.BodyPublishers.ofString(JSON_MAPPER.writeValueAsString(body)))
456+
.build();
457+
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
458+
459+
assertThat(response.statusCode()).isEqualTo(400);
460+
assertThat(errorCode(response)).isEqualTo(ErrorCodes.HEADER_MISMATCH);
461+
}
462+
405463
@Test
406464
void headerMismatchIsRejected() throws Exception {
407465
Map<String, Object> params = new HashMap<>();

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -279,6 +279,32 @@ void cancelledNotificationStopsOutputForThatRequest() throws Exception {
279279
await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> assertThat(sawCancel.get()).isTrue());
280280
}
281281

282+
@Test
283+
void legacyInitializeIsAnsweredWithSupportedVersions() throws Exception {
284+
start(McpServer.builder().serverInfo(SERVER_INFO).jsonMapper(this.jsonMapper).build());
285+
286+
sendRaw("""
287+
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25",\
288+
"capabilities":{},"clientInfo":{"name":"legacy-client","version":"1.0.0"}}}""");
289+
290+
String response = readLineWithTimeout();
291+
assertThatJson(response).isEqualTo(json("""
292+
{
293+
"jsonrpc": "2.0",
294+
"id": 1,
295+
"error": {
296+
"code": %d,
297+
"message": "${json-unit.any-string}",
298+
"data": {
299+
"supported": ["2026-07-28"],
300+
"requested": "2025-11-25"
301+
}
302+
}
303+
}
304+
""".formatted(ErrorCodes.UNSUPPORTED_PROTOCOL_VERSION)));
305+
assertThatJson(response).inPath("$.error.message").asString().contains("2026-07-28");
306+
}
307+
282308
@Test
283309
void invalidJsonProducesParseError() throws Exception {
284310
McpRequestManager manager = managerOf((transportContext, request) -> Mono

0 commit comments

Comments
 (0)