Deprecate roots, sampling, logging

Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>

Author: Kehrlann

CHANGELOG.md

@@ -36,6 +36,16 @@ Versioning follows [Semantic Versioning](https://semver.org/); see
   `equals` and `hashCode`. With `putAll`, transports can layer their own entries
   over the context a user's extractor returns, and comparing contexts was never
   a goal; read entries via `get(String)` instead.
+- Deprecate the roots, sampling and logging APIs that initiate these features, following
+  [SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging), which
+  deprecates them as of the 2026-07-28 specification revision. This covers `McpSyncClient`/`McpAsyncClient`
+  (`addRoot`, `removeRoot`, `rootsListChangedNotification`, `setLoggingLevel`), the server exchanges
+  (`createMessage`, `listRoots`, `loggingNotification`), and the `roots`, `sampling` and `logging` capability
+  builder methods. In the 2026-07-28 API it also covers `InputRequiredResult.builder()`'s `createMessage` and
+  `listRoots`, and `MetaKeys.LOG_LEVEL`. The builder methods that register handlers for these features
+  (`roots`, `sampling` and `loggingConsumer(s)` on the client, `rootsChangeHandler(s)` on the server) are not
+  deprecated, since the specification requires implementations to keep handling them for peers that still use
+  them. Behavior and the wire format are unchanged.
 
 ## 2.0.1 — 2026-08-19
 

docs/client.md

@@ -247,6 +247,9 @@ var capabilities = ClientCapabilities.builder()
 
 ### Roots Support
 
+!!! warning "Deprecated"
+    Roots are deprecated as of MCP protocol version 2026-07-28 ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)) and may be removed from a protocol revision released on or after 2027-07-28. They still work unchanged in this SDK, and the methods that initiate them are marked `@Deprecated`. Pass directories or files to servers via tool parameters, resource URIs, or server configuration instead. See the [deprecated features registry](https://modelcontextprotocol.io/specification/2026-07-28/deprecated).
+
 Roots define the boundaries of where servers can operate within the filesystem:
 
 ```java
@@ -268,6 +271,9 @@ The roots capability allows servers to:
 
 ### Sampling Support
 
+!!! warning "Deprecated"
+    Sampling is deprecated as of MCP protocol version 2026-07-28 ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)) and may be removed from a protocol revision released on or after 2027-07-28. It still works unchanged in this SDK, and the methods that initiate it are marked `@Deprecated`. Servers should integrate directly with LLM provider APIs instead. See the [deprecated features registry](https://modelcontextprotocol.io/specification/2026-07-28/deprecated).
+
 Sampling enables servers to request LLM interactions ("completions" or "generations") through the client:
 
 ```java
@@ -387,6 +393,9 @@ server.sendElicitationComplete(exchange.sessionId(),
 
 ### Logging Support
 
+!!! warning "Deprecated"
+    MCP logging is deprecated as of MCP protocol version 2026-07-28 ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)) and may be removed from a protocol revision released on or after 2027-07-28. It still works unchanged in this SDK, and the methods that initiate it are marked `@Deprecated`. Servers should log to stderr (stdio transport) or use [OpenTelemetry](https://opentelemetry.io/) instead. See the [deprecated features registry](https://modelcontextprotocol.io/specification/2026-07-28/deprecated).
+
 The client can register a logging consumer to receive log messages from the server and set the minimum logging level to filter messages:
 
 ```java

docs/server-modern.md

@@ -658,17 +658,21 @@ missing, without running the handler:
 === "Sync"
 
     ```java
-    ClientCapabilities needsSampling = ClientCapabilities.builder().sampling().build();
+    ClientCapabilities needsForms = ClientCapabilities.builder()
+        .elicitation(new ClientCapabilities.Elicitation(new ClientCapabilities.Elicitation.Form(), null))
+        .build();
 
-    McpSyncTool summarize = McpSyncTool.of(summarizeDefinition, needsSampling, handler);
+    McpSyncTool greet = McpSyncTool.of(greetDefinition, needsForms, handler);
     ```
 
 === "Async"
 
     ```java
-    ClientCapabilities needsSampling = ClientCapabilities.builder().sampling().build();
+    ClientCapabilities needsForms = ClientCapabilities.builder()
+        .elicitation(new ClientCapabilities.Elicitation(new ClientCapabilities.Elicitation.Form(), null))
+        .build();
 
-    McpAsyncTool summarize = McpAsyncTool.of(summarizeDefinition, needsSampling, handler);
+    McpAsyncTool greet = McpAsyncTool.of(greetDefinition, needsForms, handler);
     ```
 
 `McpSyncResource.of(...)` and `McpSyncPrompt.of(...)` take the same optional argument.
@@ -748,6 +752,9 @@ travels in `requestState` (see [Carrying State Across Rounds](#carrying-state-ac
 `createMessage(key, CreateMessageRequest)` and `listRoots(key)`. `InputResponses.get(...)` converts a response
 to a type of your choice, such as `ElicitResult`, `CreateMessageResult` or `ListRootsResult`; it returns `null`
 when there is no response under the key and answers malformed responses with an invalid-params error.
+`createMessage` and `listRoots` are deprecated, because the 2026-07-28 revision deprecates sampling and roots
+([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)). Prefer elicitation,
+or call an LLM provider API directly from the server.
 
 A handler may only request input the client declared it can provide. Requesting anything else is a server bug
 and is answered with an internal error. Either check `ctx.clientCapabilities()` before asking, or declare the

docs/server.md

@@ -846,6 +846,9 @@ Completions can be registered for both `PromptReference` and `ResourceReference`
 
 ### Using Sampling from a Server
 
+!!! warning "Deprecated"
+    Sampling is deprecated as of MCP protocol version 2026-07-28 ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)) and may be removed from a protocol revision released on or after 2027-07-28. It still works unchanged in this SDK, and the methods that initiate it are marked `@Deprecated`. Servers should integrate directly with LLM provider APIs instead. See the [deprecated features registry](https://modelcontextprotocol.io/specification/2026-07-28/deprecated).
+
 To use [Sampling capabilities](https://modelcontextprotocol.io/specification/2025-11-25/client/sampling), connect to a client that supports sampling.
 No special server configuration is needed, but verify client sampling support before making requests.
 Learn about [client sampling support](client.md#sampling-support).
@@ -1097,6 +1100,9 @@ The async equivalent, `McpAsyncServerExchange.ping()`, returns a `Mono<Object>`
 
 ### Logging Support
 
+!!! warning "Deprecated"
+    MCP logging is deprecated as of MCP protocol version 2026-07-28 ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)) and may be removed from a protocol revision released on or after 2027-07-28. It still works unchanged in this SDK, and the methods that initiate it are marked `@Deprecated`. Servers should log to stderr (stdio transport) or use [OpenTelemetry](https://opentelemetry.io/) instead. See the [deprecated features registry](https://modelcontextprotocol.io/specification/2026-07-28/deprecated).
+
 The server provides structured logging capabilities that allow sending log messages to clients with different severity levels.
 Log notifications can only be sent from within an existing client session, such as tools, resources, and prompts calls.
 

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

@@ -492,7 +492,12 @@ public Mono<Object> ping() {
 	 * Adds a new root to the client's root list.
 	 * @param root The root to add.
 	 * @return A Mono that completes when the root is added and notifications are sent.
+	 * @deprecated Roots are deprecated as of MCP protocol version 2026-07-28 (SEP-2577)
+	 * and may be removed from a protocol revision released on or after 2027-07-28. Pass
+	 * directories or files to servers via tool parameters, resource URIs, or server
+	 * configuration instead.
 	 */
+	@Deprecated
 	public Mono<Void> addRoot(Root root) {
 
 		if (root == null) {
@@ -524,7 +529,12 @@ public Mono<Void> addRoot(Root root) {
 	 * Removes a root from the client's root list.
 	 * @param rootUri The URI of the root to remove.
 	 * @return A Mono that completes when the root is removed and notifications are sent.
+	 * @deprecated Roots are deprecated as of MCP protocol version 2026-07-28 (SEP-2577)
+	 * and may be removed from a protocol revision released on or after 2027-07-28. Pass
+	 * directories or files to servers via tool parameters, resource URIs, or server
+	 * configuration instead.
 	 */
+	@Deprecated
 	public Mono<Void> removeRoot(String rootUri) {
 
 		if (rootUri == null) {
@@ -555,7 +565,12 @@ public Mono<Void> removeRoot(String rootUri) {
 	 * methods automatically send the roots/list_changed notification if the client is in
 	 * an initialized state.
 	 * @return A Mono that completes when the notification is sent.
+	 * @deprecated Roots are deprecated as of MCP protocol version 2026-07-28 (SEP-2577)
+	 * and may be removed from a protocol revision released on or after 2027-07-28. Pass
+	 * directories or files to servers via tool parameters, resource URIs, or server
+	 * configuration instead.
 	 */
+	@Deprecated
 	public Mono<Void> rootsListChangedNotification() {
 		return this.initializer.withInitialization("sending roots list changed notification",
 				init -> init.mcpSession().sendNotification(McpSchema.METHOD_NOTIFICATION_ROOTS_LIST_CHANGED));
@@ -1109,7 +1124,11 @@ private NotificationHandler asyncLoggingNotificationHandler(
 	 * @param loggingLevel The minimum logging level to receive.
 	 * @return A Mono that completes when the logging level is set.
 	 * @see McpSchema.LoggingLevel
+	 * @deprecated Logging is deprecated as of MCP protocol version 2026-07-28 (SEP-2577)
+	 * and may be removed from a protocol revision released on or after 2027-07-28.
+	 * Servers should log to stderr (stdio transport) or use OpenTelemetry instead.
 	 */
+	@Deprecated
 	public Mono<Void> setLoggingLevel(LoggingLevel loggingLevel) {
 		if (loggingLevel == null) {
 			return Mono.error(new IllegalArgumentException("Logging level must not be null"));

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

@@ -267,6 +267,10 @@ public SyncSpec clientInfo(Implementation clientInfo) {
 		 * Sets the root URIs that this client can access. Roots define the base URIs for
 		 * resources that the client can request from the server. For example, a root
 		 * might be "file://workspace" for accessing workspace files.
+		 * <p>
+		 * Roots are deprecated as of MCP protocol version 2026-07-28 (SEP-2577). This
+		 * method is not deprecated because the specification requires clients to keep
+		 * answering {@code roots/list} for servers that still use roots.
 		 * @param roots A list of root definitions. Must not be null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if roots is null
@@ -282,6 +286,10 @@ public SyncSpec roots(List<Root> roots) {
 		/**
 		 * Sets the root URIs that this client can access, using a varargs parameter for
 		 * convenience. This is an alternative to {@link #roots(List)}.
+		 * <p>
+		 * Roots are deprecated as of MCP protocol version 2026-07-28 (SEP-2577). This
+		 * method is not deprecated because the specification requires clients to keep
+		 * answering {@code roots/list} for servers that still use roots.
 		 * @param roots An array of root definitions. Must not be null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if roots is null
@@ -299,6 +307,10 @@ public SyncSpec roots(Root... roots) {
 		 * Sets a custom sampling handler for processing message creation requests. The
 		 * sampling handler can modify or validate messages before they are sent to the
 		 * server, enabling custom processing logic.
+		 * <p>
+		 * Sampling is deprecated as of MCP protocol version 2026-07-28 (SEP-2577). This
+		 * method is not deprecated because the specification requires clients to keep
+		 * handling {@code sampling/createMessage} for servers that still use sampling.
 		 * @param samplingHandler A function that processes message requests and returns
 		 * results. Must not be null.
 		 * @return This builder instance for method chaining
@@ -405,6 +417,10 @@ public SyncSpec promptsChangeConsumer(Consumer<List<McpSchema.Prompt>> promptsCh
 		 * Adds a consumer to be notified when logging messages are received from the
 		 * server. This allows the client to react to log messages, such as warnings or
 		 * errors, that are sent by the server.
+		 * <p>
+		 * Logging is deprecated as of MCP protocol version 2026-07-28 (SEP-2577). This
+		 * method is not deprecated because the specification requires clients to keep
+		 * handling log messages from servers that still send them.
 		 * @param loggingConsumer A consumer that receives logging messages. Must not be
 		 * null.
 		 * @return This builder instance for method chaining
@@ -419,6 +435,10 @@ public SyncSpec loggingConsumer(Consumer<McpSchema.LoggingMessageNotification> l
 		 * Adds multiple consumers to be notified when logging messages are received from
 		 * the server. This allows the client to react to log messages, such as warnings
 		 * or errors, that are sent by the server.
+		 * <p>
+		 * Logging is deprecated as of MCP protocol version 2026-07-28 (SEP-2577). This
+		 * method is not deprecated because the specification requires clients to keep
+		 * handling log messages from servers that still send them.
 		 * @param loggingConsumers A list of consumers that receive logging messages. Must
 		 * not be null.
 		 * @return This builder instance for method chaining
@@ -702,6 +722,10 @@ public AsyncSpec clientInfo(Implementation clientInfo) {
 		 * Sets the root URIs that this client can access. Roots define the base URIs for
 		 * resources that the client can request from the server. For example, a root
 		 * might be "file://workspace" for accessing workspace files.
+		 * <p>
+		 * Roots are deprecated as of MCP protocol version 2026-07-28 (SEP-2577). This
+		 * method is not deprecated because the specification requires clients to keep
+		 * answering {@code roots/list} for servers that still use roots.
 		 * @param roots A list of root definitions. Must not be null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if roots is null
@@ -717,6 +741,10 @@ public AsyncSpec roots(List<Root> roots) {
 		/**
 		 * Sets the root URIs that this client can access, using a varargs parameter for
 		 * convenience. This is an alternative to {@link #roots(List)}.
+		 * <p>
+		 * Roots are deprecated as of MCP protocol version 2026-07-28 (SEP-2577). This
+		 * method is not deprecated because the specification requires clients to keep
+		 * answering {@code roots/list} for servers that still use roots.
 		 * @param roots An array of root definitions. Must not be null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if roots is null
@@ -734,6 +762,10 @@ public AsyncSpec roots(Root... roots) {
 		 * Sets a custom sampling handler for processing message creation requests. The
 		 * sampling handler can modify or validate messages before they are sent to the
 		 * server, enabling custom processing logic.
+		 * <p>
+		 * Sampling is deprecated as of MCP protocol version 2026-07-28 (SEP-2577). This
+		 * method is not deprecated because the specification requires clients to keep
+		 * handling {@code sampling/createMessage} for servers that still use sampling.
 		 * @param samplingHandler A function that processes message requests and returns
 		 * results. Must not be null.
 		 * @return This builder instance for method chaining
@@ -842,6 +874,10 @@ public AsyncSpec promptsChangeConsumer(Function<List<McpSchema.Prompt>, Mono<Voi
 		 * Adds a consumer to be notified when logging messages are received from the
 		 * server. This allows the client to react to log messages, such as warnings or
 		 * errors, that are sent by the server.
+		 * <p>
+		 * Logging is deprecated as of MCP protocol version 2026-07-28 (SEP-2577). This
+		 * method is not deprecated because the specification requires clients to keep
+		 * handling log messages from servers that still send them.
 		 * @param loggingConsumer A consumer that receives logging messages. Must not be
 		 * null.
 		 * @return This builder instance for method chaining
@@ -856,6 +892,10 @@ public AsyncSpec loggingConsumer(Function<McpSchema.LoggingMessageNotification,
 		 * Adds multiple consumers to be notified when logging messages are received from
 		 * the server. This allows the client to react to log messages, such as warnings
 		 * or errors, that are sent by the server.
+		 * <p>
+		 * Logging is deprecated as of MCP protocol version 2026-07-28 (SEP-2577). This
+		 * method is not deprecated because the specification requires clients to keep
+		 * handling log messages from servers that still send them.
 		 * @param loggingConsumers A list of consumers that receive logging messages. Must
 		 * not be null.
 		 * @return This builder instance for method chaining

mcp-core/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java

@@ -192,21 +192,36 @@ public McpSchema.InitializeResult initialize() {
 
 	/**
 	 * Send a roots/list_changed notification.
+	 * @deprecated Roots are deprecated as of MCP protocol version 2026-07-28 (SEP-2577)
+	 * and may be removed from a protocol revision released on or after 2027-07-28. Pass
+	 * directories or files to servers via tool parameters, resource URIs, or server
+	 * configuration instead.
 	 */
+	@Deprecated
 	public void rootsListChangedNotification() {
 		withProvidedContext(this.delegate.rootsListChangedNotification()).block();
 	}
 
 	/**
 	 * Add a roots dynamically.
+	 * @deprecated Roots are deprecated as of MCP protocol version 2026-07-28 (SEP-2577)
+	 * and may be removed from a protocol revision released on or after 2027-07-28. Pass
+	 * directories or files to servers via tool parameters, resource URIs, or server
+	 * configuration instead.
 	 */
+	@Deprecated
 	public void addRoot(McpSchema.Root root) {
 		this.delegate.addRoot(root).block();
 	}
 
 	/**
 	 * Remove a root dynamically.
+	 * @deprecated Roots are deprecated as of MCP protocol version 2026-07-28 (SEP-2577)
+	 * and may be removed from a protocol revision released on or after 2027-07-28. Pass
+	 * directories or files to servers via tool parameters, resource URIs, or server
+	 * configuration instead.
 	 */
+	@Deprecated
 	public void removeRoot(String rootUri) {
 		this.delegate.removeRoot(rootUri).block();
 	}
@@ -426,7 +441,11 @@ public GetPromptResult getPrompt(GetPromptRequest getPromptRequest) {
 	/**
 	 * Client can set the minimum logging level it wants to receive from the server.
 	 * @param loggingLevel the min logging level
+	 * @deprecated Logging is deprecated as of MCP protocol version 2026-07-28 (SEP-2577)
+	 * and may be removed from a protocol revision released on or after 2027-07-28.
+	 * Servers should log to stderr (stdio transport) or use OpenTelemetry instead.
 	 */
+	@Deprecated
 	public void setLoggingLevel(McpSchema.LoggingLevel loggingLevel) {
 		withProvidedContext(this.delegate.setLoggingLevel(loggingLevel)).block();