feat: deprecate roots, sampling, and logging runtime APIs (SEP-2577) (modelcontextprotocol#2268)

Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>

Author: mattzcarey

.changeset/sep-2577-deprecate-runtime-apis.md

@@ -0,0 +1,7 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/server': patch
+'@modelcontextprotocol/client': patch
+---
+
+Mark the roots, sampling, and logging runtime APIs as `@deprecated` per SEP-2577 (deprecated as of protocol version 2026-07-28; functional for at least twelve months). Annotates `Server.createMessage`/`listRoots`/`sendLoggingMessage`, `McpServer.sendLoggingMessage`, `Client.setLoggingLevel`/`sendRootsListChanged`, the `ServerContext.mcpReq.log`/`requestSampling` helpers, and the `roots`/`sampling`/`logging` capability schema fields. JSDoc/docs only — no behavior change.

docs/client.md

@@ -404,6 +404,9 @@ client.setNotificationHandler('notifications/resources/list_changed', async () =
 });
 ```
 
+> [!WARNING]
+> MCP logging (including `setLoggingLevel()` and `notifications/message`) is deprecated as of protocol version 2026-07-28 (SEP-2577). It remains fully functional during the deprecation window (at least twelve months); see the [deprecated features registry](https://modelcontextprotocol.io/specification/draft/deprecated). Servers should migrate to stderr logging (STDIO) or OpenTelemetry.
+
 To control the minimum severity of log messages the server sends, use {@linkcode @modelcontextprotocol/client!client/client.Client#setLoggingLevel | setLoggingLevel()}:
 
 ```ts source="../examples/client/src/clientGuide.examples.ts#setLoggingLevel_basic"
@@ -431,6 +434,9 @@ const client = new Client(
 
 ### Sampling
 
+> [!WARNING]
+> Sampling is deprecated as of protocol version 2026-07-28 (SEP-2577). It remains fully functional during the deprecation window (at least twelve months); see the [deprecated features registry](https://modelcontextprotocol.io/specification/draft/deprecated). Servers should migrate to calling LLM provider APIs directly.
+
 When a server needs an LLM completion during tool execution, it sends a `sampling/createMessage` request to the client (see [Sampling](https://modelcontextprotocol.io/docs/learn/client-concepts#sampling) in the MCP overview). Register a handler to fulfill it:
 
 ```ts source="../examples/client/src/clientGuide.examples.ts#sampling_handler"
@@ -472,6 +478,9 @@ For a full form-based elicitation handler with AJV validation, see [`simpleStrea
 
 ### Roots
 
+> [!WARNING]
+> Roots are deprecated as of protocol version 2026-07-28 (SEP-2577). They remain fully functional during the deprecation window (at least twelve months); see the [deprecated features registry](https://modelcontextprotocol.io/specification/draft/deprecated). Migrate to passing paths via tool parameters, resource URIs, or configuration.
+
 Roots let the client expose filesystem boundaries to the server (see [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) in the MCP overview). Declare the `roots` capability and register a `roots/list` handler:
 
 ```ts source="../examples/client/src/clientGuide.examples.ts#roots_handler"

docs/server.md

@@ -312,6 +312,9 @@ server.registerPrompt(
 
 ## Logging
 
+> [!WARNING]
+> MCP logging is deprecated as of protocol version 2026-07-28 (SEP-2577). It remains fully functional during the deprecation window (at least twelve months); see the [deprecated features registry](https://modelcontextprotocol.io/specification/draft/deprecated). Migrate to stderr logging (STDIO servers) or OpenTelemetry.
+
 Logging lets your server send structured diagnostics — debug traces, progress updates, warnings — to the connected client as notifications (see [Logging](https://modelcontextprotocol.io/specification/latest/server/utilities/logging) in the MCP specification).
 
 Declare the `logging` capability, then call `ctx.mcpReq.log(level, data)` (from {@linkcode @modelcontextprotocol/server!index.ServerContext | ServerContext}) inside any handler:
@@ -384,6 +387,9 @@ MCP is bidirectional — servers can send requests *to* the client during tool e
 
 ### Sampling
 
+> [!WARNING]
+> Sampling is deprecated as of protocol version 2026-07-28 (SEP-2577). It remains fully functional during the deprecation window (at least twelve months); see the [deprecated features registry](https://modelcontextprotocol.io/specification/draft/deprecated). Migrate to calling LLM provider APIs directly from your server.
+
 Sampling lets a tool handler request an LLM completion from the connected client — the handler describes a prompt and the client returns the model's response (see [Sampling](https://modelcontextprotocol.io/docs/learn/client-concepts#sampling) in the MCP overview). Use sampling when a tool needs the model to generate or transform text mid-execution.
 
 Call `ctx.mcpReq.requestSampling(params)` (from {@linkcode @modelcontextprotocol/server!index.ServerContext | ServerContext}) inside a tool handler:
@@ -478,6 +484,9 @@ For runnable examples, see [`elicitationFormExample.ts`](https://github.com/mode
 
 ### Roots
 
+> [!WARNING]
+> Roots are deprecated as of protocol version 2026-07-28 (SEP-2577). They remain fully functional during the deprecation window (at least twelve months); see the [deprecated features registry](https://modelcontextprotocol.io/specification/draft/deprecated). Migrate to passing paths via tool parameters, resource URIs, or configuration.
+
 Roots let a tool handler discover the client's workspace directories — for example, to scope a file search or identify project boundaries (see [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) in the MCP overview). Call {@linkcode @modelcontextprotocol/server!server/server.Server#listRoots | server.server.listRoots()} (requires the client to declare the `roots` capability):
 
 ```ts source="../examples/server/src/serverGuide.examples.ts#registerTool_roots"

packages/client/src/client/client.ts

@@ -189,6 +189,12 @@ export type ClientOptions = ProtocolOptions & {
  * `sampling/createMessage` and `elicitation/create`, the handler is automatically wrapped with
  * schema validation for both the incoming request and the returned result.
  *
+ * Note: the `roots/list` and `sampling/createMessage` handler surfaces (and the corresponding
+ * `roots` and `sampling` capabilities) are deprecated as of protocol version 2026-07-28
+ * (SEP-2577). They remain functional during the deprecation window (at least twelve months).
+ * Migrate sampling to calling LLM provider APIs directly, and roots to passing paths via tool
+ * parameters, resource URIs, or configuration.
+ *
  * @example Handling a sampling request
  * ```ts source="./client.examples.ts#Client_setRequestHandler_sampling"
  * client.setRequestHandler('sampling/createMessage', async request => {
@@ -499,6 +505,8 @@ export class Client extends Protocol<ClientContext> {
 
     protected assertCapabilityForMethod(method: RequestMethod | string): void {
         switch (method as ClientRequest['method']) {
+            // Deprecated as of protocol version 2026-07-28 (SEP-2577); remains
+            // functional during the deprecation window (at least twelve months).
             case 'logging/setLevel': {
                 if (!this._serverCapabilities?.logging) {
                     throw new SdkError(SdkErrorCode.CapabilityNotSupported, `Server does not support logging (required for ${method})`);
@@ -562,6 +570,8 @@ export class Client extends Protocol<ClientContext> {
 
     protected assertNotificationCapability(method: NotificationMethod | string): void {
         switch (method as ClientNotification['method']) {
+            // Deprecated as of protocol version 2026-07-28 (SEP-2577); remains
+            // functional during the deprecation window (at least twelve months).
             case 'notifications/roots/list_changed': {
                 if (!this._capabilities.roots?.listChanged) {
                     throw new SdkError(
@@ -591,6 +601,8 @@ export class Client extends Protocol<ClientContext> {
 
     protected assertRequestHandlerCapability(method: string): void {
         switch (method) {
+            // Deprecated as of protocol version 2026-07-28 (SEP-2577); remains
+            // functional during the deprecation window (at least twelve months).
             case 'sampling/createMessage': {
                 if (!this._capabilities.sampling) {
                     throw new SdkError(
@@ -611,6 +623,8 @@ export class Client extends Protocol<ClientContext> {
                 break;
             }
 
+            // Deprecated as of protocol version 2026-07-28 (SEP-2577); remains
+            // functional during the deprecation window (at least twelve months).
             case 'roots/list': {
                 if (!this._capabilities.roots) {
                     throw new SdkError(
@@ -637,7 +651,13 @@ export class Client extends Protocol<ClientContext> {
         return this._requestWithSchema({ method: 'completion/complete', params }, CompleteResultSchema, options);
     }
 
-    /** Sets the minimum severity level for log messages sent by the server. */
+    /**
+     * Sets the minimum severity level for log messages sent by the server.
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+     * Remains functional during the deprecation window (at least twelve months).
+     * Migrate to stderr logging (STDIO servers) or OpenTelemetry.
+     */
     async setLoggingLevel(level: LoggingLevel, options?: RequestOptions) {
         return this._requestWithSchema({ method: 'logging/setLevel', params: { level } }, EmptyResultSchema, options);
     }
@@ -935,7 +955,13 @@ export class Client extends Protocol<ClientContext> {
         this.setNotificationHandler(notificationMethod, handler);
     }
 
-    /** Notifies the server that the client's root list has changed. Requires the `roots.listChanged` capability. */
+    /**
+     * Notifies the server that the client's root list has changed. Requires the `roots.listChanged` capability.
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+     * Remains functional during the deprecation window (at least twelve months).
+     * Migrate to passing paths via tool parameters, resource URIs, or configuration.
+     */
     async sendRootsListChanged() {
         return this.notification({ method: 'notifications/roots/list_changed' });
     }

packages/core/src/shared/protocol.ts

@@ -211,6 +211,10 @@ export type ServerContext = BaseContext & {
         /**
          * Send a log message notification to the client.
          * Respects the client's log level filter set via logging/setLevel.
+         *
+         * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+         * Remains functional during the deprecation window (at least twelve months).
+         * Migrate to stderr logging (STDIO servers) or OpenTelemetry.
          */
         log: (level: LoggingLevel, data: unknown, logger?: string) => Promise<void>;
 
@@ -221,6 +225,10 @@ export type ServerContext = BaseContext & {
 
         /**
          * Request LLM sampling from the client.
+         *
+         * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+         * Remains functional during the deprecation window (at least twelve months).
+         * Migrate to calling LLM provider APIs directly.
          */
         requestSampling: (
             params: CreateMessageRequest['params'],

packages/core/src/types/schemas.ts

@@ -421,6 +421,10 @@ export const ClientCapabilitiesSchema = z.object({
     experimental: z.record(z.string(), JSONObjectSchema).optional(),
     /**
      * Present if the client supports sampling from an LLM.
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577); remains
+     * in the specification for at least twelve months. Migrate to calling LLM
+     * provider APIs directly.
      */
     sampling: z
         .object({
@@ -441,6 +445,10 @@ export const ClientCapabilitiesSchema = z.object({
     elicitation: ElicitationCapabilitySchema.optional(),
     /**
      * Present if the client supports listing roots.
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577); remains
+     * in the specification for at least twelve months. Migrate to passing paths via
+     * tool parameters, resource URIs, or configuration.
      */
     roots: z
         .object({
@@ -486,6 +494,10 @@ export const ServerCapabilitiesSchema = z.object({
     experimental: z.record(z.string(), JSONObjectSchema).optional(),
     /**
      * Present if the server supports sending log messages to the client.
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577); remains
+     * in the specification for at least twelve months. Migrate to stderr logging
+     * (STDIO servers) or OpenTelemetry.
      */
     logging: JSONObjectSchema.optional(),
     /**

packages/core/src/types/types.ts

@@ -225,9 +225,23 @@ export type Role = Infer<typeof RoleSchema>;
 
 /* Initialization */
 export type Implementation = Infer<typeof ImplementationSchema>;
+/**
+ * Capabilities a client may support.
+ *
+ * Note: the `roots` and `sampling` capabilities are deprecated as of protocol
+ * version 2026-07-28 (SEP-2577); they remain in the specification for at least
+ * twelve months. See `ClientCapabilitiesSchema`.
+ */
 export type ClientCapabilities = Infer<typeof ClientCapabilitiesSchema>;
 export type InitializeRequestParams = Infer<typeof InitializeRequestParamsSchema>;
 export type InitializeRequest = Infer<typeof InitializeRequestSchema>;
+/**
+ * Capabilities a server may support.
+ *
+ * Note: the `logging` capability is deprecated as of protocol version
+ * 2026-07-28 (SEP-2577); it remains in the specification for at least twelve
+ * months. See `ServerCapabilitiesSchema`.
+ */
 export type ServerCapabilities = Infer<typeof ServerCapabilitiesSchema>;
 export type InitializeResult = Infer<typeof InitializeResultSchema>;
 export type InitializedNotification = Infer<typeof InitializedNotificationSchema>;

packages/server/src/server/mcp.ts

@@ -926,6 +926,10 @@ export class McpServer {
      *     data: 'Processing complete'
      * });
      * ```
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+     * Remains functional during the deprecation window (at least twelve months).
+     * Migrate to stderr logging (STDIO servers) or OpenTelemetry.
      */
     async sendLoggingMessage(params: LoggingMessageNotification['params'], sessionId?: string) {
         return this.server.sendLoggingMessage(params, sessionId);

packages/server/src/server/server.ts

@@ -113,6 +113,13 @@ export class Server extends Protocol<ServerContext> {
         }
     }
 
+    /**
+     * Registers the built-in `logging/setLevel` request handler.
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+     * Remains functional during the deprecation window (at least twelve months).
+     * Migrate to stderr logging (STDIO servers) or OpenTelemetry.
+     */
     private _registerLoggingHandler(): void {
         this.setRequestHandler('logging/setLevel', async (request, ctx) => {
             const transportSessionId: string | undefined =
@@ -133,6 +140,9 @@ export class Server extends Protocol<ServerContext> {
             ...ctx,
             mcpReq: {
                 ...ctx.mcpReq,
+                // Deprecated as of protocol version 2026-07-28 (SEP-2577): `log` and
+                // `requestSampling` remain functional during the deprecation window
+                // (at least twelve months). See ServerContext for migration guidance.
                 log: (level, data, logger) => this.sendLoggingMessage({ level, data, logger }),
                 elicitInput: (params, options) => this.elicitInput(params, options),
                 requestSampling: (params, options) => this.createMessage(params, options)
@@ -410,18 +420,30 @@ export class Server extends Protocol<ServerContext> {
     /**
      * Request LLM sampling from the client (without tools).
      * Returns single content block for backwards compatibility.
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+     * Remains functional during the deprecation window (at least twelve months).
+     * Migrate to calling LLM provider APIs directly.
      */
     async createMessage(params: CreateMessageRequestParamsBase, options?: RequestOptions): Promise<CreateMessageResult>;
 
     /**
      * Request LLM sampling from the client with tool support.
      * Returns content that may be a single block or array (for parallel tool calls).
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+     * Remains functional during the deprecation window (at least twelve months).
+     * Migrate to calling LLM provider APIs directly.
      */
     async createMessage(params: CreateMessageRequestParamsWithTools, options?: RequestOptions): Promise<CreateMessageResultWithTools>;
 
     /**
      * Request LLM sampling from the client.
      * When tools may or may not be present, returns the union type.
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+     * Remains functional during the deprecation window (at least twelve months).
+     * Migrate to calling LLM provider APIs directly.
      */
     async createMessage(
         params: CreateMessageRequest['params'],
@@ -576,6 +598,13 @@ export class Server extends Protocol<ServerContext> {
             );
     }
 
+    /**
+     * Requests the list of roots from the client.
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+     * Remains functional during the deprecation window (at least twelve months).
+     * Migrate to passing paths via tool parameters, resource URIs, or configuration.
+     */
     async listRoots(params?: ListRootsRequest['params'], options?: RequestOptions) {
         return this._requestWithSchema({ method: 'roots/list', params }, ListRootsResultSchema, options);
     }
@@ -586,6 +615,10 @@ export class Server extends Protocol<ServerContext> {
      * @see {@linkcode LoggingMessageNotification}
      * @param params
      * @param sessionId Optional for stateless transports and backward compatibility.
+     *
+     * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577).
+     * Remains functional during the deprecation window (at least twelve months).
+     * Migrate to stderr logging (STDIO servers) or OpenTelemetry.
      */
     async sendLoggingMessage(params: LoggingMessageNotification['params'], sessionId?: string) {
         if (this._capabilities.logging && !this.isMessageIgnored(params.level, sessionId)) {