From fa548d74010d04bf1d7c037179de7dec6dc473e5 Mon Sep 17 00:00:00 2001 From: Guglielmo Colombo Date: Thu, 16 Jul 2026 11:11:22 +0200 Subject: [PATCH] docs: update docs (#1089) --- docs/client.md | 8 ++++++-- docs/protocol.md | 17 +++++++++++++++++ docs/server.md | 7 ++++++- internal/docs/client.src.md | 8 ++++++-- internal/docs/protocol.src.md | 16 ++++++++++++++++ internal/docs/server.src.md | 7 ++++++- 6 files changed, 57 insertions(+), 6 deletions(-) diff --git a/docs/client.md b/docs/client.md index e262f34..13169d6 100644 --- a/docs/client.md +++ b/docs/client.md @@ -257,8 +257,12 @@ default. The middleware: The middleware is enabled by default. To opt out, set [`ClientOptions.MultiRoundTrip.Disabled = true`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#MultiRoundTripOptions); -the client will then surface `InputRequiredResult` values directly to the -caller and your code must fulfil the requests manually. +the client will then surface input-required results directly to the caller +(the returned `CallToolResult`, `GetPromptResult`, or `ReadResourceResult` +will report `NeedsInput() == true` and expose the server's `InputRequests` +and opaque `RequestState`). Your code must fulfil each request and re-issue +the original call with `InputResponses` set and `RequestState` echoed +back. For legacy (`<= 2025-11-25`) servers, the SDK transparently sends server requests on the legacy server-initiated channel; the MRTR machinery is a diff --git a/docs/protocol.md b/docs/protocol.md index 408442e..f973ae3 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -4,6 +4,7 @@ 1. [Lifecycle](#lifecycle) 1. [Discovery (`server/discover`)](#discovery-(server/discover)) 1. [Per-request `_meta` keys](#per-request-meta-keys) + 1. [Subscriptions (`subscriptions/listen`)](#subscriptions-(subscriptions/listen)) 1. [Transports](#transports) 1. [Stdio Transport](#stdio-transport) 1. [Streamable Transport](#streamable-transport) @@ -141,6 +142,22 @@ Server-side handlers can read them through `ServerRequest[P].ProtocolVersion()`, `ServerRequest[P].ClientInfo()`, and `ServerRequest[P].ClientCapabilities()`. +### Subscriptions (`subscriptions/listen`) + +Introduced in `2026-07-28` by +[SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575), +`subscriptions/listen` replaces the legacy `resources/subscribe` RPC and +the GET-based SSE endpoint with a single long-lived request that +multiplexes every kind of server-to-client change notification a client +opts in to. On the wire the client sends one `subscriptions/listen` +request whose `notifications` field enumerates what it wants +(`toolsListChanged`, `promptsListChanged`, `resourcesListChanged`, and/or +a list of resource URIs in `resourceSubscriptions`); the server replies +first with a `notifications/subscriptions/acknowledged` notification +reporting the honored subset, then streams every change notification on +the same request, and finally closes with a `SubscriptionsListenResult` +when it tears the subscription down. + ## Transports A diff --git a/docs/server.md b/docs/server.md index 573c846..9f0f870 100644 --- a/docs/server.md +++ b/docs/server.md @@ -147,7 +147,12 @@ and to unsubscribe. Set [`ClientOptions.ResourceUpdatedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.ResourceUpdatedHandler) -to be notified of changes to subscribed resources. +to be notified of changes to subscribed resources. On `2026-07-28` and +later sessions the SDK delivers these notifications over a +`subscriptions/listen` stream instead of the legacy `resources/subscribe` +RPC; see [Subscriptions +(`subscriptions/listen`)](protocol.md#subscriptions-subscriptionslisten) +for the wire-level details. **Server-side**: Use diff --git a/internal/docs/client.src.md b/internal/docs/client.src.md index e0613eb..6d14ee9 100644 --- a/internal/docs/client.src.md +++ b/internal/docs/client.src.md @@ -106,8 +106,12 @@ default. The middleware: The middleware is enabled by default. To opt out, set [`ClientOptions.MultiRoundTrip.Disabled = true`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#MultiRoundTripOptions); -the client will then surface `InputRequiredResult` values directly to the -caller and your code must fulfil the requests manually. +the client will then surface input-required results directly to the caller +(the returned `CallToolResult`, `GetPromptResult`, or `ReadResourceResult` +will report `NeedsInput() == true` and expose the server's `InputRequests` +and opaque `RequestState`). Your code must fulfil each request and re-issue +the original call with `InputResponses` set and `RequestState` echoed +back. For legacy (`<= 2025-11-25`) servers, the SDK transparently sends server requests on the legacy server-initiated channel; the MRTR machinery is a diff --git a/internal/docs/protocol.src.md b/internal/docs/protocol.src.md index 5bdbac3..d80db04 100644 --- a/internal/docs/protocol.src.md +++ b/internal/docs/protocol.src.md @@ -88,6 +88,22 @@ Server-side handlers can read them through `ServerRequest[P].ProtocolVersion()`, `ServerRequest[P].ClientInfo()`, and `ServerRequest[P].ClientCapabilities()`. +### Subscriptions (`subscriptions/listen`) + +Introduced in `2026-07-28` by +[SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575), +`subscriptions/listen` replaces the legacy `resources/subscribe` RPC and +the GET-based SSE endpoint with a single long-lived request that +multiplexes every kind of server-to-client change notification a client +opts in to. On the wire the client sends one `subscriptions/listen` +request whose `notifications` field enumerates what it wants +(`toolsListChanged`, `promptsListChanged`, `resourcesListChanged`, and/or +a list of resource URIs in `resourceSubscriptions`); the server replies +first with a `notifications/subscriptions/acknowledged` notification +reporting the honored subset, then streams every change notification on +the same request, and finally closes with a `SubscriptionsListenResult` +when it tears the subscription down. + ## Transports A diff --git a/internal/docs/server.src.md b/internal/docs/server.src.md index f2e3f3a..756bba3 100644 --- a/internal/docs/server.src.md +++ b/internal/docs/server.src.md @@ -65,7 +65,12 @@ and to unsubscribe. Set [`ClientOptions.ResourceUpdatedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.ResourceUpdatedHandler) -to be notified of changes to subscribed resources. +to be notified of changes to subscribed resources. On `2026-07-28` and +later sessions the SDK delivers these notifications over a +`subscriptions/listen` stream instead of the legacy `resources/subscribe` +RPC; see [Subscriptions +(`subscriptions/listen`)](protocol.md#subscriptions-subscriptionslisten) +for the wire-level details. **Server-side**: Use