Skip to content

Commit 449a7d6

Browse files
committed
fix: return HTTP 404 for METHOD_NOT_FOUND in stateless transport (modelcontextprotocol#1072)
The HttpServletStatelessServerTransport was returning HTTP 200 for all JSON-RPC responses, including METHOD_NOT_FOUND errors. Per the MCP Streamable HTTP specification (2026-07-28), an unrecognized method must return HTTP 404 with JSON-RPC error code -32601, not HTTP 500 or 200. This caused OpenAI's hosted MCP client to receive HTTP 500 (or 200 with an error body it could not process) when sending server/discover requests, resulting in HTTP 424 external_connector_error from the Responses API. The fix maps METHOD_NOT_FOUND (-32601) responses to HTTP 404 at the transport layer. All other JSON-RPC errors continue to use HTTP 200 per standard JSON-RPC conventions.
1 parent 24fbb11 commit 449a7d6

2 files changed

Lines changed: 92 additions & 1 deletion

File tree

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

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -195,7 +195,12 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
195195

196196
response.setContentType(APPLICATION_JSON);
197197
response.setCharacterEncoding(UTF_8);
198-
response.setStatus(HttpServletResponse.SC_OK);
198+
199+
int httpStatus = HttpServletResponse.SC_OK;
200+
if (jsonrpcResponse.error() != null) {
201+
httpStatus = mapJsonRpcErrorToHttpStatus(jsonrpcResponse.error().code());
202+
}
203+
response.setStatus(httpStatus);
199204

200205
String jsonResponseText = jsonMapper.writeValueAsString(jsonrpcResponse);
201206
PrintWriter writer = response.getWriter();
@@ -249,6 +254,21 @@ else if (message instanceof McpSchema.JSONRPCNotification jsonrpcNotification) {
249254
}
250255
}
251256

257+
/**
258+
* Maps a JSON-RPC error code to an appropriate HTTP status code per the MCP
259+
* Streamable HTTP specification (2026-07-28). Only METHOD_NOT_FOUND is mapped to a
260+
* non-200 status (HTTP 404) as specified by the protocol. All other JSON-RPC errors
261+
* are returned with HTTP 200 per standard JSON-RPC conventions.
262+
* @param jsonRpcErrorCode The JSON-RPC error code
263+
* @return The corresponding HTTP status code
264+
*/
265+
private static int mapJsonRpcErrorToHttpStatus(int jsonRpcErrorCode) {
266+
if (jsonRpcErrorCode == McpSchema.ErrorCodes.METHOD_NOT_FOUND) {
267+
return HttpServletResponse.SC_NOT_FOUND;
268+
}
269+
return HttpServletResponse.SC_OK;
270+
}
271+
252272
/**
253273
* Sends an error response to the client.
254274
* @param response The HTTP servlet response

‎mcp-test/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -915,6 +915,77 @@ public void cancel() {
915915
assertThat(response.statusCode()).isEqualTo(HttpServletResponse.SC_REQUEST_ENTITY_TOO_LARGE);
916916
}
917917

918+
@Test
919+
void testMissingHandlerReturnsHttp404WithMethodNotFoundError() throws Exception {
920+
var mcpServer = McpServer.sync(mcpStatelessServerTransport)
921+
.serverInfo("test-server", "1.0.0")
922+
.capabilities(ServerCapabilities.builder().build())
923+
.build();
924+
925+
// Use MockHttpServletRequest/Response to directly verify the HTTP 404 status
926+
// and JSON-RPC METHOD_NOT_FOUND error, since a real HTTP client treats 404
927+
// as a transport-level error per the spec.
928+
McpSchema.JSONRPCRequest jsonrpcRequest = new McpSchema.JSONRPCRequest("foo/bar", "test-request-123");
929+
930+
MockHttpServletRequest request = new MockHttpServletRequest("POST", CUSTOM_MESSAGE_ENDPOINT);
931+
MockHttpServletResponse response = new MockHttpServletResponse();
932+
933+
byte[] content = JSON_MAPPER.writeValueAsBytes(jsonrpcRequest);
934+
request.setContent(content);
935+
request.addHeader("Content-Type", APPLICATION_JSON);
936+
request.addHeader("Content-Length", Integer.toString(content.length));
937+
request.addHeader("Accept", APPLICATION_JSON + ", " + TEXT_EVENT_STREAM);
938+
request.addHeader(HttpHeaders.PROTOCOL_VERSION, ProtocolVersions.MCP_2025_03_26);
939+
940+
mcpStatelessServerTransport.service(request, response);
941+
942+
assertThat(response.getStatus()).isEqualTo(HttpServletResponse.SC_NOT_FOUND);
943+
944+
McpSchema.JSONRPCResponse jsonrpcResponse = JSON_MAPPER.readValue(response.getContentAsByteArray(),
945+
McpSchema.JSONRPCResponse.class);
946+
947+
assertThat(jsonrpcResponse).isNotNull();
948+
assertThat(jsonrpcResponse.error()).isNotNull();
949+
assertThat(jsonrpcResponse.error().code()).isEqualTo(ErrorCodes.METHOD_NOT_FOUND);
950+
assertThat(jsonrpcResponse.error().message()).isEqualTo("Method not found: foo/bar");
951+
952+
mcpServer.closeGracefully();
953+
}
954+
955+
@Test
956+
void testUnknownMethodReturnsHttp404WithMethodNotFoundError() throws Exception {
957+
var mcpServer = McpServer.sync(mcpStatelessServerTransport)
958+
.serverInfo("test-server", "1.0.0")
959+
.capabilities(ServerCapabilities.builder().build())
960+
.build();
961+
962+
McpSchema.JSONRPCRequest jsonrpcRequest = new McpSchema.JSONRPCRequest("server/discover", "discover-1");
963+
964+
MockHttpServletRequest request = new MockHttpServletRequest("POST", CUSTOM_MESSAGE_ENDPOINT);
965+
MockHttpServletResponse response = new MockHttpServletResponse();
966+
967+
byte[] content = JSON_MAPPER.writeValueAsBytes(jsonrpcRequest);
968+
request.setContent(content);
969+
request.addHeader("Content-Type", APPLICATION_JSON);
970+
request.addHeader("Content-Length", Integer.toString(content.length));
971+
request.addHeader("Accept", APPLICATION_JSON + ", " + TEXT_EVENT_STREAM);
972+
request.addHeader(HttpHeaders.PROTOCOL_VERSION, ProtocolVersions.MCP_2025_03_26);
973+
974+
mcpStatelessServerTransport.service(request, response);
975+
976+
assertThat(response.getStatus()).isEqualTo(HttpServletResponse.SC_NOT_FOUND);
977+
978+
McpSchema.JSONRPCResponse jsonrpcResponse = JSON_MAPPER.readValue(response.getContentAsByteArray(),
979+
McpSchema.JSONRPCResponse.class);
980+
981+
assertThat(jsonrpcResponse).isNotNull();
982+
assertThat(jsonrpcResponse.error()).isNotNull();
983+
assertThat(jsonrpcResponse.error().code()).isEqualTo(ErrorCodes.METHOD_NOT_FOUND);
984+
assertThat(jsonrpcResponse.error().message()).isEqualTo("Method not found: server/discover");
985+
986+
mcpServer.close();
987+
}
988+
918989
private double evaluateExpression(String expression) {
919990
// Simple expression evaluator for testing
920991
return switch (expression) {

0 commit comments

Comments
 (0)