mcp: Deprecate roots, sampling and logging (SEP-2577) (#1017)

guglielmo-san · web-flow · commit b6649db4f925 · 2026-06-23T11:11:08.000+02:00
Fixes #1013
diff --git a/README.md b/README.md
@@ -44,6 +44,13 @@ The following table shows which versions of the Go SDK support which versions of
 
 \*\* Partial support for 2025-11-25 (client side OAuth and Sampling with tools not available).
 
+The roots, sampling, and logging features are deprecated as of protocol version
+2026-07-28 by
+[SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging).
+The SDK continues to support them for compatibility during the deprecation
+window (at least twelve months). See the individual feature documentation for
+migration guidance.
+
 New releases of the SDK target only supported versions of Go. See
 https://go.dev/doc/devel/release#policy for more information.
 
diff --git a/conformance/everything-server/main.go b/conformance/everything-server/main.go
@@ -5,6 +5,8 @@
 // The conformance server implements features required for MCP conformance testing.
 // It mirrors the functionality of the TypeScript conformance server at
 // https://github.com/modelcontextprotocol/conformance/blob/main/examples/servers/typescript/everything-server.ts
+//
+//lint:file-ignore SA1019 conformance server exercises deprecated SEP-2577 APIs (roots, sampling, logging).
 package main
 
 import (
diff --git a/docs/client.md b/docs/client.md
@@ -10,6 +10,13 @@
 
 ## Roots
 
+> **Note:** The roots feature is deprecated as of protocol version 2026-07-28
+> ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)).
+> It remains fully functional during the deprecation window (at least twelve
+> months). The SDK continues to support roots for compatibility. New code
+> should pass paths via tool parameters, resource URIs, or configuration
+> instead.
+
 MCP allows clients to specify a set of filesystem
 ["roots"](https://modelcontextprotocol.io/specification/2025-06-18/client/roots).
 The SDK supports this as follows:
@@ -77,6 +84,13 @@ func Example_roots() {
 
 ## Sampling
 
+> **Note:** The sampling feature is deprecated as of protocol version
+> 2026-07-28
+> ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)).
+> It remains fully functional during the deprecation window (at least twelve
+> months). The SDK continues to support sampling for compatibility. Servers
+> that need LLM completions should call LLM provider APIs directly.
+
 [Sampling](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling)
 is a way for servers to leverage the client's AI capabilities. It is
 implemented in the SDK as follows:
diff --git a/docs/server.md b/docs/server.md
@@ -474,6 +474,13 @@ _ = mcp.NewServer(&mcp.Implementation{Name: "server"}, &mcp.ServerOptions{
 
 ### Logging
 
+> **Note:** The logging feature is deprecated as of protocol version
+> 2026-07-28
+> ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)).
+> It remains fully functional during the deprecation window (at least twelve
+> months). The SDK continues to support logging for compatibility. Servers
+> should migrate to stderr logging (for STDIO transports) or OpenTelemetry.
+
 MCP servers can send logging messages to MCP clients.
 (This form of logging is distinct from server-side logging, where the
 server produces logs that remain server-side, for use by server maintainers.)
diff --git a/examples/server/distributed/main.go b/examples/server/distributed/main.go
@@ -16,6 +16,8 @@
 // Example:
 //
 //	./distributed -http=localhost:8080 -child_ports=8081,8082
+//
+//lint:file-ignore SA1019 example server exercises deprecated SEP-2577 logging API for demonstration.
 package main
 
 import (
diff --git a/examples/server/everything/main.go b/examples/server/everything/main.go
@@ -3,6 +3,8 @@
 // license that can be found in the LICENSE file.
 
 // The everything server implements all supported features of an MCP server.
+//
+//lint:file-ignore SA1019 example server exercises deprecated SEP-2577 APIs (roots, sampling, logging) for demonstration.
 package main
 
 import (
diff --git a/internal/docs/client.src.md b/internal/docs/client.src.md
@@ -4,6 +4,13 @@
 
 ## Roots
 
+> **Note:** The roots feature is deprecated as of protocol version 2026-07-28
+> ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)).
+> It remains fully functional during the deprecation window (at least twelve
+> months). The SDK continues to support roots for compatibility. New code
+> should pass paths via tool parameters, resource URIs, or configuration
+> instead.
+
 MCP allows clients to specify a set of filesystem
 ["roots"](https://modelcontextprotocol.io/specification/2025-06-18/client/roots).
 The SDK supports this as follows:
@@ -26,6 +33,13 @@ method. To receive notifications about root changes, set
 
 ## Sampling
 
+> **Note:** The sampling feature is deprecated as of protocol version
+> 2026-07-28
+> ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)).
+> It remains fully functional during the deprecation window (at least twelve
+> months). The SDK continues to support sampling for compatibility. Servers
+> that need LLM completions should call LLM provider APIs directly.
+
 [Sampling](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling)
 is a way for servers to leverage the client's AI capabilities. It is
 implemented in the SDK as follows:
diff --git a/internal/docs/server.src.md b/internal/docs/server.src.md
@@ -236,6 +236,13 @@ requests.
 
 ### Logging
 
+> **Note:** The logging feature is deprecated as of protocol version
+> 2026-07-28
+> ([SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging)).
+> It remains fully functional during the deprecation window (at least twelve
+> months). The SDK continues to support logging for compatibility. Servers
+> should migrate to stderr logging (for STDIO transports) or OpenTelemetry.
+
 MCP servers can send logging messages to MCP clients.
 (This form of logging is distinct from server-side logging, where the
 server produces logs that remain server-side, for use by server maintainers.)
diff --git a/internal/readme/README.src.md b/internal/readme/README.src.md
@@ -43,6 +43,13 @@ The following table shows which versions of the Go SDK support which versions of
 
 \*\* Partial support for 2025-11-25 (client side OAuth and Sampling with tools not available).
 
+The roots, sampling, and logging features are deprecated as of protocol version
+2026-07-28 by
+[SEP-2577](https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging).
+The SDK continues to support them for compatibility during the deprecation
+window (at least twelve months). See the individual feature documentation for
+migration guidance.
+
 New releases of the SDK target only supported versions of Go. See
 https://go.dev/doc/devel/release#policy for more information.
 
diff --git a/mcp/capabilities_test.go b/mcp/capabilities_test.go
@@ -2,6 +2,8 @@
 // Use of this source code is governed by an MIT-style
 // license that can be found in the LICENSE file.
 
+//lint:file-ignore SA1019 tests exercise deprecated SEP-2577 APIs (roots, sampling, logging).
+
 package mcp
 
 import (
diff --git a/mcp/client.go b/mcp/client.go
@@ -82,6 +82,12 @@ type ClientOptions struct {
 	// &SamplingCapabilities{}. If [ClientOptions.Capabilities] is set and has a
 	// non nil value for [ClientCapabilities.Sampling], that value overrides the
 	// inferred capability.
+	//
+	// Deprecated: the sampling feature is deprecated as of protocol version
+	// 2026-07-28 (SEP-2577). It remains functional during the deprecation
+	// window (at least twelve months). Migrate to calling LLM provider APIs
+	// directly from your server. See
+	// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 	CreateMessageHandler func(context.Context, *CreateMessageRequest) (*CreateMessageResult, error)
 	// CreateMessageWithToolsHandler handles incoming sampling/createMessage
 	// requests that may involve tool use. It returns
@@ -95,6 +101,12 @@ type ClientOptions struct {
 	//
 	// It is a panic to set both CreateMessageHandler and
 	// CreateMessageWithToolsHandler.
+	//
+	// Deprecated: the sampling feature is deprecated as of protocol version
+	// 2026-07-28 (SEP-2577). It remains functional during the deprecation
+	// window (at least twelve months). Migrate to calling LLM provider APIs
+	// directly from your server. See
+	// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 	CreateMessageWithToolsHandler func(context.Context, *CreateMessageWithToolsRequest) (*CreateMessageWithToolsResult, error)
 	// ElicitationHandler handles incoming requests for elicitation/create.
 	//
@@ -152,10 +164,17 @@ type ClientOptions struct {
 	// ElicitationCompleteHandler handles incoming notifications for notifications/elicitation/complete.
 	ElicitationCompleteHandler func(context.Context, *ElicitationCompleteNotificationRequest)
 	// Handlers for notifications from the server.
-	ToolListChangedHandler      func(context.Context, *ToolListChangedRequest)
-	PromptListChangedHandler    func(context.Context, *PromptListChangedRequest)
-	ResourceListChangedHandler  func(context.Context, *ResourceListChangedRequest)
-	ResourceUpdatedHandler      func(context.Context, *ResourceUpdatedNotificationRequest)
+	ToolListChangedHandler     func(context.Context, *ToolListChangedRequest)
+	PromptListChangedHandler   func(context.Context, *PromptListChangedRequest)
+	ResourceListChangedHandler func(context.Context, *ResourceListChangedRequest)
+	ResourceUpdatedHandler     func(context.Context, *ResourceUpdatedNotificationRequest)
+	// LoggingMessageHandler handles incoming notifications/message
+	// notifications from the server.
+	//
+	// Deprecated: the logging feature is deprecated as of protocol version
+	// 2026-07-28 (SEP-2577). It remains functional during the deprecation
+	// window (at least twelve months). See
+	// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 	LoggingMessageHandler       func(context.Context, *LoggingMessageRequest)
 	ProgressNotificationHandler func(context.Context, *ProgressNotificationClientRequest)
 	// MultiRoundTrip configures the automatic MultiRoundTrip (Multi Round-Trip Requests) middleware.
@@ -615,6 +634,12 @@ func (cs *ClientSession) startKeepalive(interval time.Duration) {
 // AddRoots adds the given roots to the client,
 // replacing any with the same URIs,
 // and notifies any connected servers.
+//
+// Deprecated: the roots feature is deprecated as of protocol version
+// 2026-07-28 (SEP-2577). It remains functional during the deprecation window
+// (at least twelve months). Migrate to passing paths via tool parameters,
+// resource URIs, or configuration. See
+// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 func (c *Client) AddRoots(roots ...*Root) {
 	// Only notify if something could change.
 	if len(roots) == 0 {
@@ -627,6 +652,12 @@ func (c *Client) AddRoots(roots ...*Root) {
 // RemoveRoots removes the roots with the given URIs,
 // and notifies any connected servers if the list has changed.
 // It is not an error to remove a nonexistent root.
+//
+// Deprecated: the roots feature is deprecated as of protocol version
+// 2026-07-28 (SEP-2577). It remains functional during the deprecation window
+// (at least twelve months). Migrate to passing paths via tool parameters,
+// resource URIs, or configuration. See
+// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 func (c *Client) RemoveRoots(uris ...string) {
 	changeAndNotify(c, notificationRootsListChanged, &RootsListChangedParams{},
 		func() bool { return c.roots.remove(uris...) })
@@ -1242,6 +1273,14 @@ func (cs *ClientSession) CallTool(ctx context.Context, params *CallToolParams) (
 	return handleSend[*CallToolResult](ctx, methodCallTool, newClientRequest(cs, orZero[Params](params)))
 }
 
+// SetLoggingLevel sets the minimum severity level for log messages sent by
+// the server.
+//
+// Deprecated: the logging feature is deprecated as of protocol version
+// 2026-07-28 (SEP-2577). It remains functional during the deprecation window
+// (at least twelve months). Migrate to consuming stderr output (for STDIO
+// servers) or OpenTelemetry. See
+// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 func (cs *ClientSession) SetLoggingLevel(ctx context.Context, params *SetLoggingLevelParams) error {
 	_, err := handleSend[*emptyResult](ctx, methodSetLevel, newClientRequest(cs, orZero[Params](params)))
 	return err
diff --git a/mcp/client_example_test.go b/mcp/client_example_test.go
@@ -2,6 +2,8 @@
 // Use of this source code is governed by an MIT-style
 // license that can be found in the LICENSE file.
 
+//lint:file-ignore SA1019 examples exercise deprecated SEP-2577 APIs (roots, sampling) for demonstration.
+
 package mcp_test
 
 import (
diff --git a/mcp/client_test.go b/mcp/client_test.go
@@ -2,6 +2,8 @@
 // Use of this source code is governed by an MIT-style
 // license that can be found in the LICENSE file.
 
+//lint:file-ignore SA1019 tests exercise deprecated SEP-2577 APIs (roots, sampling, logging).
+
 package mcp
 
 import (
diff --git a/mcp/content.go b/mcp/content.go
@@ -189,6 +189,11 @@ func (c *EmbeddedResource) fromWire(wire *wireContent) {
 
 // ToolUseContent represents a request from the assistant to invoke a tool.
 // This content type is only valid in sampling messages.
+//
+// Deprecated: the sampling feature is deprecated as of protocol version
+// 2026-07-28 (SEP-2577). It remains functional during the deprecation window
+// (at least twelve months). See
+// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 type ToolUseContent struct {
 	// ID is a unique identifier for this tool use, used to match with ToolResultContent.
 	ID string
@@ -229,6 +234,11 @@ func (c *ToolUseContent) fromWire(wire *wireContent) {
 
 // ToolResultContent represents the result of a tool invocation.
 // This content type is only valid in sampling messages with role "user".
+//
+// Deprecated: the sampling feature is deprecated as of protocol version
+// 2026-07-28 (SEP-2577). It remains functional during the deprecation window
+// (at least twelve months). See
+// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 type ToolResultContent struct {
 	// ToolUseID references the ID from the corresponding ToolUseContent.
 	ToolUseID string
diff --git a/mcp/logging.go b/mcp/logging.go
@@ -69,6 +69,11 @@ func compareLevels(l1, l2 LoggingLevel) int {
 }
 
 // LoggingHandlerOptions are options for a LoggingHandler.
+//
+// Deprecated: the logging feature is deprecated as of protocol version
+// 2026-07-28 (SEP-2577). It remains functional during the deprecation window
+// (at least twelve months). See
+// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 type LoggingHandlerOptions struct {
 	// The value for the "logger" field of logging notifications.
 	LoggerName string
@@ -79,6 +84,11 @@ type LoggingHandlerOptions struct {
 }
 
 // A LoggingHandler is a [slog.Handler] for MCP.
+//
+// Deprecated: the logging feature is deprecated as of protocol version
+// 2026-07-28 (SEP-2577). It remains functional during the deprecation window
+// (at least twelve months). See
+// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 type LoggingHandler struct {
 	opts LoggingHandlerOptions
 	ss   *ServerSession
@@ -101,6 +111,11 @@ func ensureLogger(l *slog.Logger) *slog.Logger {
 
 // NewLoggingHandler creates a [LoggingHandler] that logs to the given [ServerSession] using a
 // [slog.JSONHandler].
+//
+// Deprecated: the logging feature is deprecated as of protocol version
+// 2026-07-28 (SEP-2577). It remains functional during the deprecation window
+// (at least twelve months). See
+// https://modelcontextprotocol.io/seps/2577-deprecate-roots-sampling-and-logging.
 func NewLoggingHandler(ss *ServerSession, opts *LoggingHandlerOptions) *LoggingHandler {
 	var buf bytes.Buffer
 	jsonHandler := slog.NewJSONHandler(&buf, &slog.HandlerOptions{
diff --git a/mcp/mcp_test.go b/mcp/mcp_test.go
@@ -2,6 +2,8 @@
 // Use of this source code is governed by an MIT-style
 // license that can be found in the LICENSE file.
 
+//lint:file-ignore SA1019 tests exercise deprecated SEP-2577 APIs (roots, sampling, logging).
+
 package mcp
 
 import (
diff --git a/mcp/mrtr_test.go b/mcp/mrtr_test.go
@@ -2,6 +2,8 @@
 // Use of this source code is governed by the license
 // that can be found in the LICENSE file.
 
+//lint:file-ignore SA1019 tests exercise deprecated SEP-2577 APIs (roots, sampling, logging).
+
 package mcp
 
 import (
diff --git a/mcp/protocol.go b/mcp/protocol.go
diff --git a/mcp/sampling_test.go b/mcp/sampling_test.go
diff --git a/mcp/server.go b/mcp/server.go
diff --git a/mcp/server_example_test.go b/mcp/server_example_test.go
diff --git a/mcp/streamable_test.go b/mcp/streamable_test.go
