modelcontextprotocol/typescript-sdk
Watch
1
0
Fork
You've already forked typescript-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

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

Browse source 
Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>
This commit is contained in:
Matt 2026-06-15 13:19:45 +01:00 • committed by GitHub
commit 49c0a711c8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 124 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

7
.changeset/sep-2577-deprecate-runtime-apis.md Normal file
View file

@ -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.

9
docs/client.md
View file

@ -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"

9
docs/server.md
View file

@ -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"

30
packages/client/src/client/client.ts
View file

@ -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' });
}

8
packages/core/src/shared/protocol.ts
View file

@ -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'],

12
packages/core/src/types/schemas.ts
View file

@ -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(),
/**

14
packages/core/src/types/types.ts
View file

@ -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>;

4
packages/server/src/server/mcp.ts
View file

@ -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);

33
packages/server/src/server/server.ts
View file

@ -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)) {