feat: add ignorable JSON-RPC methods support for both client and server

- Add ignorableJsonRpcMethods support to McpClientSession and McpServerSession
- Implement request and notification filtering for specified methods
- Add default ignorable methods: notifications/cancelled, notifications/stderr
- Extend both client and server builders with ignorableJsonRpcMethods() methods
- Support both List<String> and varargs configurations
- Add comprehensive test coverage for client and server-side functionality
- Maintain full backward compatibility with deprecated constructors
- Log ignored methods as DEBUG for debugging visibility

This feature allows both MCP clients and servers to gracefully handle
unknown or unwanted JSON-RPC methods without generating errors, improving
compatibility with various implementations and reducing log noise.

Resolves #416, #377

Related to #130 It provides a workaround until the `notification/cancelled` is supposed.

Signed-off-by: Christian Tzolov <[email protected]>

Author: tzolov

mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java

@@ -159,7 +159,7 @@ public class McpAsyncClient {
 	 * @param features the MCP Client supported features.
 	 */
 	McpAsyncClient(McpClientTransport transport, Duration requestTimeout, Duration initializationTimeout,
-			McpClientFeatures.Async features) {
+			McpClientFeatures.Async features, List<String> ignorableJsonRpcMethods) {
 
 		Assert.notNull(transport, "Transport must not be null");
 		Assert.notNull(requestTimeout, "Request timeout must not be null");
@@ -269,7 +269,7 @@ public class McpAsyncClient {
 		this.initializer = new LifecycleInitializer(clientCapabilities, clientInfo,
 				List.of(McpSchema.LATEST_PROTOCOL_VERSION), initializationTimeout,
 				ctx -> new McpClientSession(requestTimeout, transport, requestHandlers, notificationHandlers,
-						con -> con.contextWrite(ctx)));
+						con -> con.contextWrite(ctx), ignorableJsonRpcMethods));
 		this.transport.setExceptionHandler(this.initializer::handleException);
 	}
 

mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java

@@ -23,6 +23,7 @@
 import io.modelcontextprotocol.spec.McpSchema.Implementation;
 import io.modelcontextprotocol.spec.McpSchema.Root;
 import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.Utils;
 import reactor.core.publisher.Mono;
 
 /**
@@ -161,6 +162,12 @@ class SyncSpec {
 
 		private Duration initializationTimeout = Duration.ofSeconds(20);
 
+		/**
+		 * List of JSON-RPC methods that can be ignored. These methods will not be
+		 * processed and will not generate errors if received
+		 */
+		private final List<String> ignorableJsonRpcMethods = new ArrayList<>(Utils.DEFAULT_IGNORABLE_JSON_RPC_METHODS);
+
 		private ClientCapabilities capabilities;
 
 		private Implementation clientInfo = new Implementation("Java SDK MCP Client", "1.0.0");
@@ -215,6 +222,36 @@ public SyncSpec initializationTimeout(Duration initializationTimeout) {
 			return this;
 		}
 
+		/**
+		 * Sets the list of JSON-RPC methods that can be ignored by the client. These
+		 * methods will not be processed and will not generate errors if received.
+		 * @param ignorableJsonRpcMethods A list of JSON-RPC method names to ignore. Must
+		 * not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if ignorableJsonRpcMethods is null
+		 */
+		public SyncSpec ignorableJsonRpcMethods(List<String> ignorableJsonRpcMethods) {
+			Assert.notNull(ignorableJsonRpcMethods, "Ignorable JSON-RPC methods must not be null");
+			this.ignorableJsonRpcMethods.addAll(ignorableJsonRpcMethods);
+			return this;
+		}
+
+		/**
+		 * Sets the list of JSON-RPC methods that can be ignored by the client. These
+		 * methods will not be processed and will not generate errors if received.
+		 * @param ignorableJsonRpcMethods An array of JSON-RPC method names to ignore.
+		 * Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if ignorableJsonRpcMethods is null
+		 */
+		public SyncSpec ignorableJsonRpcMethods(String... ignorableJsonRpcMethods) {
+			Assert.notNull(ignorableJsonRpcMethods, "Ignorable JSON-RPC methods must not be null");
+			for (String method : ignorableJsonRpcMethods) {
+				this.ignorableJsonRpcMethods.add(method);
+			}
+			return this;
+		}
+
 		/**
 		 * Sets the client capabilities that will be advertised to the server during
 		 * connection initialization. Capabilities define what features the client
@@ -422,8 +459,8 @@ public McpSyncClient build() {
 
 			McpClientFeatures.Async asyncFeatures = McpClientFeatures.Async.fromSync(syncFeatures);
 
-			return new McpSyncClient(
-					new McpAsyncClient(transport, this.requestTimeout, this.initializationTimeout, asyncFeatures));
+			return new McpSyncClient(new McpAsyncClient(transport, this.requestTimeout, this.initializationTimeout,
+					asyncFeatures, this.ignorableJsonRpcMethods));
 		}
 
 	}
@@ -452,6 +489,12 @@ class AsyncSpec {
 
 		private Duration initializationTimeout = Duration.ofSeconds(20);
 
+		/**
+		 * List of JSON-RPC methods that can be ignored. These methods will not be
+		 * processed and will not generate errors if received
+		 */
+		private final List<String> ignorableJsonRpcMethods = new ArrayList<>(Utils.DEFAULT_IGNORABLE_JSON_RPC_METHODS);
+
 		private ClientCapabilities capabilities;
 
 		private Implementation clientInfo = new Implementation("Spring AI MCP Client", "0.3.1");
@@ -506,6 +549,36 @@ public AsyncSpec initializationTimeout(Duration initializationTimeout) {
 			return this;
 		}
 
+		/**
+		 * Sets the list of JSON-RPC methods that can be ignored by the client. These
+		 * methods will not be processed and will not generate errors if received.
+		 * @param ignorableJsonRpcMethods A list of JSON-RPC method names to ignore. Must
+		 * not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if ignorableJsonRpcMethods is null
+		 */
+		public AsyncSpec ignorableJsonRpcMethods(List<String> ignorableJsonRpcMethods) {
+			Assert.notNull(ignorableJsonRpcMethods, "Ignorable JSON-RPC methods must not be null");
+			this.ignorableJsonRpcMethods.addAll(ignorableJsonRpcMethods);
+			return this;
+		}
+
+		/**
+		 * Sets the list of JSON-RPC methods that can be ignored by the client. These
+		 * methods will not be processed and will not generate errors if received.
+		 * @param ignorableJsonRpcMethods An array of JSON-RPC method names to ignore.
+		 * Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if ignorableJsonRpcMethods is null
+		 */
+		public AsyncSpec ignorableJsonRpcMethods(String... ignorableJsonRpcMethods) {
+			Assert.notNull(ignorableJsonRpcMethods, "Ignorable JSON-RPC methods must not be null");
+			for (String method : ignorableJsonRpcMethods) {
+				this.ignorableJsonRpcMethods.add(method);
+			}
+			return this;
+		}
+
 		/**
 		 * Sets the client capabilities that will be advertised to the server during
 		 * connection initialization. Capabilities define what features the client
@@ -730,7 +803,8 @@ public McpAsyncClient build() {
 					new McpClientFeatures.Async(this.clientInfo, this.capabilities, this.roots,
 							this.toolsChangeConsumers, this.resourcesChangeConsumers, this.resourcesUpdateConsumers,
 							this.promptsChangeConsumers, this.loggingConsumers, this.progressConsumers,
-							this.samplingHandler, this.elicitationHandler));
+							this.samplingHandler, this.elicitationHandler),
+					this.ignorableJsonRpcMethods);
 		}
 
 	}

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java

@@ -116,6 +116,8 @@ public class McpAsyncServer {
 
 	private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
 
+	private final List<String> ignorableJsonRpcMethods;
+
 	/**
 	 * Create a new McpAsyncServer with the given transport provider and capabilities.
 	 * @param mcpTransportProvider The transport layer implementation for MCP
@@ -126,6 +128,22 @@ public class McpAsyncServer {
 	McpAsyncServer(McpServerTransportProvider mcpTransportProvider, ObjectMapper objectMapper,
 			McpServerFeatures.Async features, Duration requestTimeout,
 			McpUriTemplateManagerFactory uriTemplateManagerFactory, JsonSchemaValidator jsonSchemaValidator) {
+		this(mcpTransportProvider, objectMapper, features, requestTimeout, uriTemplateManagerFactory,
+				jsonSchemaValidator, Utils.DEFAULT_IGNORABLE_JSON_RPC_METHODS);
+	}
+
+	/**
+	 * Create a new McpAsyncServer with the given transport provider and capabilities.
+	 * @param mcpTransportProvider The transport layer implementation for MCP
+	 * communication.
+	 * @param features The MCP server supported features.
+	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * @param ignorableJsonRpcMethods List of JSON-RPC method names that should be ignored
+	 */
+	McpAsyncServer(McpServerTransportProvider mcpTransportProvider, ObjectMapper objectMapper,
+			McpServerFeatures.Async features, Duration requestTimeout,
+			McpUriTemplateManagerFactory uriTemplateManagerFactory, JsonSchemaValidator jsonSchemaValidator,
+			List<String> ignorableJsonRpcMethods) {
 		this.mcpTransportProvider = mcpTransportProvider;
 		this.objectMapper = objectMapper;
 		this.serverInfo = features.serverInfo();
@@ -138,6 +156,8 @@ public class McpAsyncServer {
 		this.completions.putAll(features.completions());
 		this.uriTemplateManagerFactory = uriTemplateManagerFactory;
 		this.jsonSchemaValidator = jsonSchemaValidator;
+		this.ignorableJsonRpcMethods = ignorableJsonRpcMethods != null ? List.copyOf(ignorableJsonRpcMethods)
+				: List.of();
 
 		Map<String, McpServerSession.RequestHandler<?>> requestHandlers = new HashMap<>();
 
@@ -190,9 +210,9 @@ public class McpAsyncServer {
 		notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_ROOTS_LIST_CHANGED,
 				asyncRootsListChangedNotificationHandler(rootsChangeConsumers));
 
-		mcpTransportProvider.setSessionFactory(
-				transport -> new McpServerSession(UUID.randomUUID().toString(), requestTimeout, transport,
-						this::asyncInitializeRequestHandler, Mono::empty, requestHandlers, notificationHandlers));
+		mcpTransportProvider.setSessionFactory(transport -> new McpServerSession(UUID.randomUUID().toString(),
+				requestTimeout, transport, this::asyncInitializeRequestHandler, Mono::empty, requestHandlers,
+				notificationHandlers, this.ignorableJsonRpcMethods));
 	}
 
 	// ---------------------------------------

mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java

@@ -24,6 +24,7 @@
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.DeafaultMcpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.McpUriTemplateManagerFactory;
+import io.modelcontextprotocol.util.Utils;
 import reactor.core.publisher.Mono;
 
 /**
@@ -212,6 +213,8 @@ class AsyncSpecification {
 
 		private Duration requestTimeout = Duration.ofSeconds(10); // Default timeout
 
+		private final List<String> ignorableJsonRpcMethods = new ArrayList<>(Utils.DEFAULT_IGNORABLE_JSON_RPC_METHODS);
+
 		private AsyncSpecification(McpServerTransportProvider transportProvider) {
 			Assert.notNull(transportProvider, "Transport provider must not be null");
 			this.transportProvider = transportProvider;
@@ -689,6 +692,34 @@ public AsyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaVali
 			return this;
 		}
 
+		/**
+		 * Adds JSON-RPC method names that should be ignored by the server. Ignored
+		 * methods will not generate error responses when received from clients, allowing
+		 * for graceful handling of unknown or unwanted methods.
+		 * @param ignorableJsonRpcMethods List of method names to ignore. Must not be
+		 * null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if ignorableJsonRpcMethods is null
+		 */
+		public AsyncSpecification ignorableJsonRpcMethods(List<String> ignorableJsonRpcMethods) {
+			Assert.notNull(ignorableJsonRpcMethods, "Ignorable JSON-RPC methods must not be null");
+			this.ignorableJsonRpcMethods.addAll(ignorableJsonRpcMethods);
+			return this;
+		}
+
+		/**
+		 * Adds JSON-RPC method names that should be ignored by the server using varargs.
+		 * This is a convenience method for {@link #ignorableJsonRpcMethods(List)}.
+		 * @param ignorableJsonRpcMethods Method names to ignore. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if ignorableJsonRpcMethods is null
+		 */
+		public AsyncSpecification ignorableJsonRpcMethods(String... ignorableJsonRpcMethods) {
+			Assert.notNull(ignorableJsonRpcMethods, "Ignorable JSON-RPC methods must not be null");
+			this.ignorableJsonRpcMethods.addAll(List.of(ignorableJsonRpcMethods));
+			return this;
+		}
+
 		/**
 		 * Builds an asynchronous MCP server that provides non-blocking operations.
 		 * @return A new instance of {@link McpAsyncServer} configured with this builder's
@@ -701,8 +732,9 @@ public McpAsyncServer build() {
 			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
 			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
 					: new DefaultJsonSchemaValidator(mapper);
+
 			return new McpAsyncServer(this.transportProvider, mapper, features, this.requestTimeout,
-					this.uriTemplateManagerFactory, jsonSchemaValidator);
+					this.uriTemplateManagerFactory, jsonSchemaValidator, this.ignorableJsonRpcMethods);
 		}
 
 	}
@@ -766,6 +798,8 @@ class SyncSpecification {
 
 		private boolean immediateExecution = false;
 
+		private final List<String> ignorableJsonRpcMethods = new ArrayList<>(Utils.DEFAULT_IGNORABLE_JSON_RPC_METHODS);
+
 		private SyncSpecification(McpServerTransportProvider transportProvider) {
 			Assert.notNull(transportProvider, "Transport provider must not be null");
 			this.transportProvider = transportProvider;
@@ -1251,6 +1285,34 @@ public SyncSpecification immediateExecution(boolean immediateExecution) {
 			return this;
 		}
 
+		/**
+		 * Adds JSON-RPC method names that should be ignored by the server. Ignored
+		 * methods will not generate error responses when received from clients, allowing
+		 * for graceful handling of unknown or unwanted methods.
+		 * @param ignorableJsonRpcMethods List of method names to ignore. Must not be
+		 * null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if ignorableJsonRpcMethods is null
+		 */
+		public SyncSpecification ignorableJsonRpcMethods(List<String> ignorableJsonRpcMethods) {
+			Assert.notNull(ignorableJsonRpcMethods, "Ignorable JSON-RPC methods must not be null");
+			this.ignorableJsonRpcMethods.addAll(ignorableJsonRpcMethods);
+			return this;
+		}
+
+		/**
+		 * Adds JSON-RPC method names that should be ignored by the server using varargs.
+		 * This is a convenience method for {@link #ignorableJsonRpcMethods(List)}.
+		 * @param ignorableJsonRpcMethods Method names to ignore. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if ignorableJsonRpcMethods is null
+		 */
+		public SyncSpecification ignorableJsonRpcMethods(String... ignorableJsonRpcMethods) {
+			Assert.notNull(ignorableJsonRpcMethods, "Ignorable JSON-RPC methods must not be null");
+			this.ignorableJsonRpcMethods.addAll(List.of(ignorableJsonRpcMethods));
+			return this;
+		}
+
 		/**
 		 * Builds a synchronous MCP server that provides blocking operations.
 		 * @return A new instance of {@link McpSyncServer} configured with this builder's
@@ -1267,7 +1329,7 @@ public McpSyncServer build() {
 					: new DefaultJsonSchemaValidator(mapper);
 
 			var asyncServer = new McpAsyncServer(this.transportProvider, mapper, asyncFeatures, this.requestTimeout,
-					this.uriTemplateManagerFactory, jsonSchemaValidator);
+					this.uriTemplateManagerFactory, jsonSchemaValidator, this.ignorableJsonRpcMethods);
 
 			return new McpSyncServer(asyncServer, this.immediateExecution);
 		}