docs: update docs (#1089)

Author: guglielmo-san

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

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

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

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

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

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