Rework MCP error handling

mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java

@@ -26,6 +26,7 @@
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpTransportException;
 import io.modelcontextprotocol.spec.McpTransportSession;
 import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import io.modelcontextprotocol.spec.McpTransportStream;
@@ -428,11 +429,11 @@ private Tuple2<Optional<String>, Iterable<McpSchema.JSONRPCMessage>> parse(Serve
 				return Tuples.of(Optional.ofNullable(event.id()), List.of(message));
 			}
 			catch (IOException ioException) {
-				throw new McpError("Error parsing JSON-RPC message: " + event.data());
+				throw new McpTransportException("Error parsing JSON-RPC message: " + event.data(), ioException);
 			}
 		}
 		else {
-			throw new McpError("Received unrecognized SSE event type: " + event.event());
+			throw new McpTransportException("Received unrecognized SSE event type: " + event.event());
 		}
 	}
 

mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java

@@ -9,9 +9,12 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.spec.McpClientInternalException;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpTransportException;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
@@ -197,13 +200,14 @@ public Mono<Void> connect(Function<Mono<JSONRPCMessage>, Mono<JSONRPCMessage>> h
 		this.inboundSubscription = events.concatMap(event -> Mono.just(event).<JSONRPCMessage>handle((e, s) -> {
 			if (ENDPOINT_EVENT_TYPE.equals(event.event())) {
 				String messageEndpointUri = event.data();
-				if (messageEndpointSink.tryEmitValue(messageEndpointUri).isSuccess()) {
+				var emitResult = messageEndpointSink.tryEmitValue(messageEndpointUri);
+				if (emitResult.isSuccess()) {
 					s.complete();
 				}
 				else {
 					// TODO: clarify with the spec if multiple events can be
 					// received
-					s.error(new McpError("Failed to handle SSE endpoint event"));
+					s.error(new McpClientInternalException("Failed to handle SSE endpoint event"));
 				}
 			}
 			else if (MESSAGE_EVENT_TYPE.equals(event.event())) {
@@ -216,7 +220,7 @@ else if (MESSAGE_EVENT_TYPE.equals(event.event())) {
 				}
 			}
 			else {
-				s.error(new McpError("Received unrecognized SSE event type: " + event.event()));
+				s.error(new McpTransportException("Received unrecognized SSE event type: " + event.event()));
 			}
 		}).transform(handler)).subscribe();
 

mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java

@@ -7,9 +7,12 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.ErrorCodes;
+import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse.JSONRPCError;
 import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.spec.McpServerTransport;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import io.modelcontextprotocol.spec.McpTransportException;
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -300,31 +303,29 @@ private Mono<ServerResponse> handleMessage(ServerRequest request) {
 		}
 
 		if (request.queryParam("sessionId").isEmpty()) {
-			return ServerResponse.badRequest().bodyValue(new McpError("Session ID missing in message endpoint"));
+			return ServerResponse.badRequest()
+				.bodyValue(McpError.builder(ErrorCodes.INVALID_REQUEST).message("Missing session ID param").build());
 		}
 
-		McpServerSession session = sessions.get(request.queryParam("sessionId").get());
+		String sessionId = request.queryParam("sessionId").get();
+		McpServerSession session = sessions.get(sessionId);
 
 		if (session == null) {
 			return ServerResponse.status(HttpStatus.NOT_FOUND)
-				.bodyValue(new McpError("Session not found: " + request.queryParam("sessionId").get()));
+				.bodyValue(McpError.builder(ErrorCodes.INVALID_REQUEST)
+					.message("SessionId not found")
+					.data("Empty sessionId: " + sessionId)
+					.build());
 		}
 
 		return request.bodyToMono(String.class).flatMap(body -> {
 			try {
 				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
-				return session.handle(message).flatMap(response -> ServerResponse.ok().build()).onErrorResume(error -> {
-					logger.error("Error processing  message: {}", error.getMessage());
-					// TODO: instead of signalling the error, just respond with 200 OK
-					// - the error is signalled on the SSE connection
-					// return ServerResponse.ok().build();
-					return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
-						.bodyValue(new McpError(error.getMessage()));
-				});
+				return session.handle(message).flatMap(response -> ServerResponse.ok().build());
 			}
 			catch (IllegalArgumentException | IOException e) {
 				logger.error("Failed to deserialize message: {}", e.getMessage());
-				return ServerResponse.badRequest().bodyValue(new McpError("Invalid message format"));
+				return ServerResponse.badRequest().bodyValue(new McpTransportException("Invalid message format", e));
 			}
 		});
 	}

mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java

@@ -13,8 +13,11 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.ErrorCodes;
+import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse.JSONRPCError;
 import io.modelcontextprotocol.spec.McpServerTransport;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import io.modelcontextprotocol.spec.McpTransportException;
 import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
@@ -300,14 +303,19 @@ private ServerResponse handleMessage(ServerRequest request) {
 		}
 
 		if (request.param("sessionId").isEmpty()) {
-			return ServerResponse.badRequest().body(new McpError("Session ID missing in message endpoint"));
+			return ServerResponse.badRequest()
+				.body(McpError.builder(ErrorCodes.INVALID_REQUEST).message("Missing session ID param").build());
 		}
 
 		String sessionId = request.param("sessionId").get();
 		McpServerSession session = sessions.get(sessionId);
 
 		if (session == null) {
-			return ServerResponse.status(HttpStatus.NOT_FOUND).body(new McpError("Session not found: " + sessionId));
+			return ServerResponse.status(HttpStatus.NOT_FOUND)
+				.body(McpError.builder(ErrorCodes.INVALID_REQUEST)
+					.message("SessionId not found")
+					.data("Empty sessionId: " + sessionId)
+					.build());
 		}
 
 		try {
@@ -321,11 +329,11 @@ private ServerResponse handleMessage(ServerRequest request) {
 		}
 		catch (IllegalArgumentException | IOException e) {
 			logger.error("Failed to deserialize message: {}", e.getMessage());
-			return ServerResponse.badRequest().body(new McpError("Invalid message format"));
+			return ServerResponse.badRequest().body(new McpTransportException("Invalid message format", e));
 		}
 		catch (Exception e) {
 			logger.error("Error handling message: {}", e.getMessage());
-			return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR).body(new McpError(e.getMessage()));
+			return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR).body(new McpTransportException(e));
 		}
 	}
 

mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java

@@ -486,7 +486,8 @@ void testAddRoot() {
 	void testAddRootWithNullValue() {
 		withClient(createMcpTransport(), mcpAsyncClient -> {
 			StepVerifier.create(mcpAsyncClient.addRoot(null))
-				.consumeErrorWith(e -> assertThat(e).isInstanceOf(McpError.class).hasMessage("Root must not be null"))
+				.consumeErrorWith(e -> assertThat(e).isInstanceOf(IllegalArgumentException.class)
+					.hasMessage("Root must not be null"))
 				.verify();
 		});
 	}
@@ -505,7 +506,7 @@ void testRemoveRoot() {
 	void testRemoveNonExistentRoot() {
 		withClient(createMcpTransport(), mcpAsyncClient -> {
 			StepVerifier.create(mcpAsyncClient.removeRoot("nonexistent-uri"))
-				.consumeErrorWith(e -> assertThat(e).isInstanceOf(McpError.class)
+				.consumeErrorWith(e -> assertThat(e).isInstanceOf(IllegalStateException.class)
 					.hasMessage("Root with uri 'nonexistent-uri' not found"))
 				.verify();
 		});

mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java

@@ -147,7 +147,7 @@ void testAddDuplicateTool() {
 			.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(duplicateTool,
 					(exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))))
 			.verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class)
+				assertThat(error).isInstanceOf(IllegalArgumentException.class)
 					.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
 			});
 
@@ -168,7 +168,7 @@ void testAddDuplicateToolCall() {
 			.tool(duplicateTool)
 			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build())).verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class)
+				assertThat(error).isInstanceOf(IllegalArgumentException.class)
 					.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
 			});
 
@@ -254,7 +254,8 @@ void testRemoveNonexistentTool() {
 			.build();
 
 		StepVerifier.create(mcpAsyncServer.removeTool("nonexistent-tool")).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class).hasMessage("Tool with name 'nonexistent-tool' not found");
+			assertThat(error).isInstanceOf(IllegalArgumentException.class)
+				.hasMessage("Tool with name 'nonexistent-tool' not found");
 		});
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -326,7 +327,7 @@ void testAddResourceWithNullSpecification() {
 
 		StepVerifier.create(mcpAsyncServer.addResource((McpServerFeatures.AsyncResourceSpecification) null))
 			.verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class).hasMessage("Resource must not be null");
+				assertThat(error).isInstanceOf(IllegalArgumentException.class).hasMessage("Resource must not be null");
 			});
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -345,7 +346,7 @@ void testAddResourceWithoutCapability() {
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
 		StepVerifier.create(serverWithoutResources.addResource(specification)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
+			assertThat(error).isInstanceOf(IllegalStateException.class)
 				.hasMessage("Server must be configured with resource capabilities");
 		});
 	}
@@ -358,7 +359,7 @@ void testRemoveResourceWithoutCapability() {
 			.build();
 
 		StepVerifier.create(serverWithoutResources.removeResource(TEST_RESOURCE_URI)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
+			assertThat(error).isInstanceOf(IllegalStateException.class)
 				.hasMessage("Server must be configured with resource capabilities");
 		});
 	}
@@ -385,7 +386,8 @@ void testAddPromptWithNullSpecification() {
 
 		StepVerifier.create(mcpAsyncServer.addPrompt((McpServerFeatures.AsyncPromptSpecification) null))
 			.verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class).hasMessage("Prompt specification must not be null");
+				assertThat(error).isInstanceOf(IllegalArgumentException.class)
+					.hasMessage("Prompt specification must not be null");
 			});
 	}
 
@@ -402,7 +404,7 @@ void testAddPromptWithoutCapability() {
 					.of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content"))))));
 
 		StepVerifier.create(serverWithoutPrompts.addPrompt(specification)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
+			assertThat(error).isInstanceOf(IllegalStateException.class)
 				.hasMessage("Server must be configured with prompt capabilities");
 		});
 	}
@@ -415,7 +417,7 @@ void testRemovePromptWithoutCapability() {
 			.build();
 
 		StepVerifier.create(serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
+			assertThat(error).isInstanceOf(IllegalStateException.class)
 				.hasMessage("Server must be configured with prompt capabilities");
 		});
 	}
@@ -448,7 +450,7 @@ void testRemoveNonexistentPrompt() {
 			.build();
 
 		StepVerifier.create(mcpAsyncServer2.removePrompt("nonexistent-prompt")).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
+			assertThat(error).isInstanceOf(IllegalArgumentException.class)
 				.hasMessage("Prompt with name 'nonexistent-prompt' not found");
 		});
 

mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java

@@ -153,7 +153,7 @@ void testAddDuplicateTool() {
 
 		assertThatThrownBy(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(duplicateTool,
 				(exchange, args) -> new CallToolResult(List.of(), false))))
-			.isInstanceOf(McpError.class)
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
@@ -172,7 +172,7 @@ void testAddDuplicateToolCall() {
 		assertThatThrownBy(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
 			.tool(duplicateTool)
 			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
-			.build())).isInstanceOf(McpError.class)
+			.build())).isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
@@ -256,7 +256,8 @@ void testRemoveNonexistentTool() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		assertThatThrownBy(() -> mcpSyncServer.removeTool("nonexistent-tool")).isInstanceOf(McpError.class)
+		assertThatThrownBy(() -> mcpSyncServer.removeTool("nonexistent-tool"))
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Tool with name 'nonexistent-tool' not found");
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
@@ -320,7 +321,7 @@ void testAddResourceWithNullSpecification() {
 			.build();
 
 		assertThatThrownBy(() -> mcpSyncServer.addResource((McpServerFeatures.SyncResourceSpecification) null))
-			.isInstanceOf(McpError.class)
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Resource must not be null");
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
@@ -337,7 +338,8 @@ void testAddResourceWithoutCapability() {
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
-		assertThatThrownBy(() -> serverWithoutResources.addResource(specification)).isInstanceOf(McpError.class)
+		assertThatThrownBy(() -> serverWithoutResources.addResource(specification))
+			.isInstanceOf(IllegalStateException.class)
 			.hasMessage("Server must be configured with resource capabilities");
 	}
 
@@ -347,7 +349,8 @@ void testRemoveResourceWithoutCapability() {
 			.serverInfo("test-server", "1.0.0")
 			.build();
 
-		assertThatThrownBy(() -> serverWithoutResources.removeResource(TEST_RESOURCE_URI)).isInstanceOf(McpError.class)
+		assertThatThrownBy(() -> serverWithoutResources.removeResource(TEST_RESOURCE_URI))
+			.isInstanceOf(IllegalStateException.class)
 			.hasMessage("Server must be configured with resource capabilities");
 	}
 
@@ -372,7 +375,7 @@ void testAddPromptWithNullSpecification() {
 			.build();
 
 		assertThatThrownBy(() -> mcpSyncServer.addPrompt((McpServerFeatures.SyncPromptSpecification) null))
-			.isInstanceOf(McpError.class)
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Prompt specification must not be null");
 	}
 
@@ -387,7 +390,8 @@ void testAddPromptWithoutCapability() {
 				(exchange, req) -> new GetPromptResult("Test prompt description", List
 					.of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content")))));
 
-		assertThatThrownBy(() -> serverWithoutPrompts.addPrompt(specification)).isInstanceOf(McpError.class)
+		assertThatThrownBy(() -> serverWithoutPrompts.addPrompt(specification))
+			.isInstanceOf(IllegalStateException.class)
 			.hasMessage("Server must be configured with prompt capabilities");
 	}
 
@@ -397,7 +401,8 @@ void testRemovePromptWithoutCapability() {
 			.serverInfo("test-server", "1.0.0")
 			.build();
 
-		assertThatThrownBy(() -> serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME)).isInstanceOf(McpError.class)
+		assertThatThrownBy(() -> serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME))
+			.isInstanceOf(IllegalStateException.class)
 			.hasMessage("Server must be configured with prompt capabilities");
 	}
 
@@ -426,7 +431,8 @@ void testRemoveNonexistentPrompt() {
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.build();
 
-		assertThatThrownBy(() -> mcpSyncServer.removePrompt("nonexistent-prompt")).isInstanceOf(McpError.class)
+		assertThatThrownBy(() -> mcpSyncServer.removePrompt("nonexistent-prompt"))
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Prompt with name 'nonexistent-prompt' not found");
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();