diff --git a/.changeset/sep-2577-deprecate-runtime-apis.md b/.changeset/sep-2577-deprecate-runtime-apis.md new file mode 100644 index 0000000000..60afaaceb2 --- /dev/null +++ b/.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. diff --git a/docs/client.md b/docs/client.md index 0c852f4e11..bfc13eeecd 100644 --- a/docs/client.md +++ b/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" diff --git a/docs/server.md b/docs/server.md index b16c24fc4d..57aca89b8c 100644 --- a/docs/server.md +++ b/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" diff --git a/packages/client/src/client/client.ts b/packages/client/src/client/client.ts index 36a98521cd..95312cf8c5 100644 --- a/packages/client/src/client/client.ts +++ b/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 { 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 { 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 { 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 { 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 { 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 { 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' }); } diff --git a/packages/core/src/shared/protocol.ts b/packages/core/src/shared/protocol.ts index ed78cc68d0..16d2181018 100644 --- a/packages/core/src/shared/protocol.ts +++ b/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; @@ -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'], diff --git a/packages/core/src/types/schemas.ts b/packages/core/src/types/schemas.ts index f472a36ff9..fe850284e2 100644 --- a/packages/core/src/types/schemas.ts +++ b/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(), /** diff --git a/packages/core/src/types/types.ts b/packages/core/src/types/types.ts index 123de7fe84..e0fe28b500 100644 --- a/packages/core/src/types/types.ts +++ b/packages/core/src/types/types.ts @@ -225,9 +225,23 @@ export type Role = Infer; /* Initialization */ export type Implementation = Infer; +/** + * 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; export type InitializeRequestParams = Infer; export type InitializeRequest = Infer; +/** + * 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; export type InitializeResult = Infer; export type InitializedNotification = Infer; diff --git a/packages/server/src/server/mcp.ts b/packages/server/src/server/mcp.ts index 40ec8bb1eb..0bdc813404 100644 --- a/packages/server/src/server/mcp.ts +++ b/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); diff --git a/packages/server/src/server/server.ts b/packages/server/src/server/server.ts index 9e117f05c3..9f2dc5ba51 100644 --- a/packages/server/src/server/server.ts +++ b/packages/server/src/server/server.ts @@ -113,6 +113,13 @@ export class Server extends Protocol { } } + /** + * 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 { ...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 { /** * 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; /** * 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; /** * 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 { ); } + /** + * 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 { * @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)) {