docs: auto-open listen filter is configured ∩ server-advertised everywhere

The behavior landed in ce9251c but the changeset, migration.md, the
autoOpenedSubscription getter JSDoc, the example header comment, and the
e2e requirement text still said the filter is 'derived from which
sub-options were set'. Sync all five to the implemented behavior (and
that auto-open is skipped — autoOpenedSubscription stays undefined — when
the intersection is empty). Rebuild examples-client dist.

Author: felixweinberger

.changeset/subscriptions-listen-client.md

@@ -3,4 +3,4 @@
 '@modelcontextprotocol/client': minor
 ---
 
-`Client.listen(filter)` opens a `subscriptions/listen` stream on a 2026-07-28-era connection, resolving once the server's acknowledged notification arrives with an `McpSubscription { honoredFilter, close() }`. Change notifications delivered on the stream dispatch to the existing `setNotificationHandler` registrations — the same handlers the 2025-era unsolicited notifications fire on a legacy connection — so `listen()` is era-transparent for consumers that already register those. `close()` closes the listen request's SSE stream (Streamable HTTP) or sends `notifications/cancelled` referencing the listen id (stdio); no automatic re-listen. On a 2025-era connection `listen()` throws a typed `MethodNotSupportedByProtocolVersion` steering to `resources/subscribe` and `ClientOptions.listChanged`. `ClientOptions.listChanged` now auto-opens a listen stream on a modern connection (filter derived from which sub-options were set; the auto-opened subscription is exposed at `client.autoOpenedSubscription`). `TransportSendOptions` gains `requestSignal` for per-request abort on the Streamable HTTP transport.
+`Client.listen(filter)` opens a `subscriptions/listen` stream on a 2026-07-28-era connection, resolving once the server's acknowledged notification arrives with an `McpSubscription { honoredFilter, close() }`. Change notifications delivered on the stream dispatch to the existing `setNotificationHandler` registrations — the same handlers the 2025-era unsolicited notifications fire on a legacy connection — so `listen()` is era-transparent for consumers that already register those. `close()` closes the listen request's SSE stream (Streamable HTTP) or sends `notifications/cancelled` referencing the listen id (stdio); no automatic re-listen. On a 2025-era connection `listen()` throws a typed `MethodNotSupportedByProtocolVersion` steering to `resources/subscribe` and `ClientOptions.listChanged`. `ClientOptions.listChanged` now auto-opens a listen stream on a modern connection — the filter is the intersection of the configured sub-options and the server-advertised `listChanged` capabilities; auto-open is skipped (`client.autoOpenedSubscription` stays `undefined`) when that intersection is empty; otherwise the auto-opened subscription is exposed at `client.autoOpenedSubscription`. `TransportSendOptions` gains `requestSignal` for per-request abort on the Streamable HTTP transport.

docs/migration.md

@@ -1172,8 +1172,8 @@ const handler = createMcpHandler(() => buildServer());
 handler.notify.toolsChanged();
 ```
 
-**Client side.** `ClientOptions.listChanged` keeps working: on a 2026-07-28 connection the SDK auto-opens a `subscriptions/listen` stream with the filter derived from which sub-options were set, so the same handlers fire on every published change (the auto-opened subscription is
-exposed at `client.autoOpenedSubscription` for `close()`). `client.listen(filter)` opens a stream explicitly and resolves once the server's acknowledged notification arrives with `{ honoredFilter, close() }`; change notifications dispatch to the existing `setNotificationHandler`
+**Client side.** `ClientOptions.listChanged` keeps working: on a 2026-07-28 connection the SDK auto-opens a `subscriptions/listen` stream whose filter is the intersection of the configured sub-options and the server-advertised `listChanged` capabilities, so the same handlers
+fire on every published change (the auto-opened subscription is exposed at `client.autoOpenedSubscription` for `close()`; when the intersection is empty auto-open is skipped and `autoOpenedSubscription` stays `undefined`). `client.listen(filter)` opens a stream explicitly and resolves once the server's acknowledged notification arrives with `{ honoredFilter, close() }`; change notifications dispatch to the existing `setNotificationHandler`
 registrations. `resources/subscribe` is 2025-only — on a 2026-07-28 connection, request `notifications/resources/updated` via the `resourceSubscriptions` field of the listen filter instead.
 
 ### Multi round-trip requests (2026-07-28): write-once handlers and the client auto-fulfilment driver

examples/client/src/subscriptionsListenClient.ts

@@ -5,8 +5,10 @@
  *
  * 1. **auto-open via `ClientOptions.listChanged`** — the same option a
  *    2025-era client sets; on a modern connection the SDK auto-opens a
- *    listen stream with the filter derived from which sub-options were set,
- *    so the configured `onChanged` handlers fire on every published change;
+ *    listen stream whose filter is the intersection of the configured
+ *    sub-options and the server-advertised `listChanged` capabilities
+ *    (auto-open is skipped when the intersection is empty), so the
+ *    configured `onChanged` handlers fire on every published change;
  * 2. **manual `client.listen()`** — opens a stream explicitly, registers a
  *    `notifications/tools/list_changed` handler the stream feeds, and closes
  *    after a few notifications.

packages/client/src/client/client.ts

@@ -1423,9 +1423,11 @@ export class Client extends Protocol<ClientContext> {
 
     /**
      * The subscription auto-opened by `ClientOptions.listChanged` on a modern
-     * connection (the listen filter derived from which sub-options were set),
-     * or `undefined` on a legacy connection or before connect. Exposed so the
-     * consumer can `close()` it.
+     * connection — the listen filter is the intersection of the configured
+     * sub-options and the server-advertised `listChanged` capabilities.
+     * `undefined` on a legacy connection, before connect, or when that
+     * intersection is empty (auto-open skipped). Exposed so the consumer can
+     * `close()` it.
      */
     get autoOpenedSubscription(): McpSubscription | undefined {
         return this._autoOpenedSubscription;

packages/client/test/client/listen.test.ts

@@ -358,7 +358,7 @@ describe('Client.listen()', () => {
         expect((error as SdkError).code).toBe(SdkErrorCode.NotConnected);
     });
 
-    it('ClientOptions.listChanged auto-opens a listen stream on a modern connection (filter derived from sub-options)', async () => {
+    it('ClientOptions.listChanged auto-opens a listen stream on a modern connection (filter = configured ∩ server-advertised)', async () => {
         const filters: unknown[] = [];
         const { clientTx } = await scriptedModern((_id, filter) => filters.push(filter));
         const onChanged = () => {};

test/e2e/requirements.ts

@@ -2695,7 +2695,7 @@ export const REQUIREMENTS: Record<string, Requirement> = {
     'typescript:subscriptions:listChanged-auto-open-modern': {
         source: 'sdk',
         behavior:
-            'ClientOptions.listChanged auto-opens a subscriptions/listen stream on a modern connection (filter derived from which sub-options were set), so the configured handlers fire on every published change. The auto-opened subscription is exposed for close.',
+            'ClientOptions.listChanged auto-opens a subscriptions/listen stream on a modern connection — the filter is the intersection of the configured sub-options and the server-advertised listChanged capabilities (auto-open is skipped and autoOpenedSubscription stays undefined when the intersection is empty) — so the configured handlers fire on every published change. The auto-opened subscription is exposed for close.',
         addedInSpecVersion: '2026-07-28',
         transports: ['entryModern'],
         note: 'Hosted by the test body via createMcpHandler so it can publish via handler.notify.'