fix(server): narrow honored listen filter against the server's declared capabilities

`honoredSubset()` now accepts an optional `ServerCapabilities` and drops
any requested notification type the server does not advertise:
`toolsListChanged` is honored only when `capabilities.tools.listChanged`
is true (likewise prompts/resources), and `resourceSubscriptions` only
when `capabilities.resources.subscribe` is true. The honored filter the
ack carries thereby reflects what the server can actually deliver.

The seam is threaded through `ListenRouterOptions.serverCapabilities` and
`StdioListenRouter`'s constructor. When omitted (the current
`createMcpHandler`/`serveStdio` wiring, where capabilities live behind a
per-request factory), the requested set is honored as-is — unchanged
behavior. Wiring the entries to supply capabilities (via a factory probe
instance) is a follow-up.

Author: felixweinberger

packages/server/src/server/listenRouter.ts

@@ -18,7 +18,7 @@
  * - The server MUST NOT deliver a notification type the client did not request.
  * - Termination is stream close (HTTP); no JSON-RPC result is ever emitted.
  */
-import type { JSONRPCRequest, RequestId, SubscriptionFilter } from '@modelcontextprotocol/core';
+import type { JSONRPCRequest, RequestId, ServerCapabilities, SubscriptionFilter } from '@modelcontextprotocol/core';
 import { SUBSCRIPTION_ID_META_KEY, SubscriptionFilterSchema } from '@modelcontextprotocol/core';
 
 import type { ServerEventBus } from './serverEventBus.js';
@@ -38,6 +38,13 @@ export interface ListenRouterOptions {
     maxSubscriptions?: number;
     /** SSE comment-frame keepalive interval; `0` disables keepalive (default 15000). */
     keepAliveMs?: number;
+    /**
+     * The server's declared capabilities. When supplied, the honored filter
+     * the ack carries is narrowed against these (a requested type the server
+     * does not advertise is dropped from the ack); when omitted, the requested
+     * set is honored as-is.
+     */
+    serverCapabilities?: ServerCapabilities;
     /** Out-of-band error reporting (never alters the response). */
     onerror?: (error: Error) => void;
 }
@@ -103,7 +110,7 @@ export interface ListenRouter {
 }
 
 export function createListenRouter(options: ListenRouterOptions): ListenRouter {
-    const { bus, onerror } = options;
+    const { bus, onerror, serverCapabilities } = options;
     const maxSubscriptions = options.maxSubscriptions ?? DEFAULT_MAX_SUBSCRIPTIONS;
     const keepAliveMs = options.keepAliveMs ?? DEFAULT_LISTEN_KEEPALIVE_MS;
 
@@ -119,7 +126,7 @@ export function createListenRouter(options: ListenRouterOptions): ListenRouter {
         if (filter === undefined) {
             return jsonRpcError(message.id, -32_602, "Invalid params: 'notifications' is required and must be a valid SubscriptionFilter");
         }
-        const honored = honoredSubset(filter);
+        const honored = honoredSubset(filter, serverCapabilities);
         // The spec carries the listen request's JSON-RPC id verbatim as the
         // subscription id; demux is per-connection (each HTTP listen has its
         // own SSE stream) so client-chosen ids cannot route across requests.
@@ -246,7 +253,10 @@ export class StdioListenRouter {
     /** Active subscriptions, keyed by the listen request's JSON-RPC id verbatim. */
     private readonly _subs = new Map<RequestId, SubscriptionFilter>();
 
-    constructor(private readonly _maxSubscriptions: number = DEFAULT_MAX_SUBSCRIPTIONS) {}
+    constructor(
+        private readonly _maxSubscriptions: number = DEFAULT_MAX_SUBSCRIPTIONS,
+        private readonly _serverCapabilities?: ServerCapabilities
+    ) {}
 
     /** Whether `id` is an active listen subscription on this connection. */
     has(id: RequestId): boolean {
@@ -270,7 +280,7 @@ export class StdioListenRouter {
                 error: { code: -32_602, message: "Invalid params: 'notifications' is required and must be a valid SubscriptionFilter" }
             };
         }
-        const honored = honoredSubset(filter);
+        const honored = honoredSubset(filter, this._serverCapabilities);
         this._subs.set(message.id, honored);
         return stampSubscriptionId({ method: 'notifications/subscriptions/acknowledged', params: { notifications: honored } }, message.id);
     }

packages/server/src/server/serverEventBus.ts

@@ -1,4 +1,4 @@
-import type { SubscriptionFilter } from '@modelcontextprotocol/core';
+import type { ServerCapabilities, SubscriptionFilter } from '@modelcontextprotocol/core';
 
 /**
  * A change event a server publishes for delivery on open `subscriptions/listen`
@@ -143,19 +143,31 @@ export function listenFilterAccepts(filter: SubscriptionFilter, event: ServerEve
 
 /**
  * The honored subset of a requested filter: keeps only the fields the client
- * explicitly opted in to (drops `false` and absent fields). The serving entry
- * sends this back in `notifications/subscriptions/acknowledged`.
+ * explicitly opted in to (drops `false` and absent fields), narrowed against
+ * the server's declared capabilities when supplied. The serving entry sends
+ * this back in `notifications/subscriptions/acknowledged` so the ack reflects
+ * what the server can actually deliver.
  *
- * The entry-handled listen router does not narrow the requested set further —
- * the bus only emits events the consumer publishes, so honoring the full
- * request is harmless when the server never publishes a given type.
+ * - `toolsListChanged` is honored only when `capabilities.tools.listChanged`
+ *   is advertised; likewise `promptsListChanged` / `resourcesListChanged`.
+ * - `resourceSubscriptions` is honored only when
+ *   `capabilities.resources.subscribe` is advertised.
+ *
+ * When `capabilities` is omitted the requested set is honored as-is (the
+ * pre-existing behavior, for callers that cannot supply capabilities at
+ * router creation time).
  */
-export function honoredSubset(requested: SubscriptionFilter): SubscriptionFilter {
+export function honoredSubset(requested: SubscriptionFilter, capabilities?: ServerCapabilities): SubscriptionFilter {
     const honored: SubscriptionFilter = {};
-    if (requested.toolsListChanged === true) honored.toolsListChanged = true;
-    if (requested.promptsListChanged === true) honored.promptsListChanged = true;
-    if (requested.resourcesListChanged === true) honored.resourcesListChanged = true;
-    if (requested.resourceSubscriptions !== undefined && requested.resourceSubscriptions.length > 0) {
+    const allow = (bit: unknown): boolean => capabilities === undefined || bit === true;
+    if (requested.toolsListChanged === true && allow(capabilities?.tools?.listChanged)) honored.toolsListChanged = true;
+    if (requested.promptsListChanged === true && allow(capabilities?.prompts?.listChanged)) honored.promptsListChanged = true;
+    if (requested.resourcesListChanged === true && allow(capabilities?.resources?.listChanged)) honored.resourcesListChanged = true;
+    if (
+        requested.resourceSubscriptions !== undefined &&
+        requested.resourceSubscriptions.length > 0 &&
+        allow(capabilities?.resources?.subscribe)
+    ) {
         honored.resourceSubscriptions = [...requested.resourceSubscriptions];
     }
     return honored;

packages/server/test/server/serverEventBus.test.ts

@@ -60,6 +60,24 @@ describe('honoredSubset', () => {
         requested.resourceSubscriptions.push('file:///b');
         expect(honored.resourceSubscriptions).toEqual(['file:///a']);
     });
+
+    it('narrows against the supplied server capabilities', () => {
+        const requested = {
+            toolsListChanged: true as const,
+            promptsListChanged: true as const,
+            resourcesListChanged: true as const,
+            resourceSubscriptions: ['file:///a']
+        };
+        // Only tools.listChanged advertised → only toolsListChanged honored.
+        expect(honoredSubset(requested, { tools: { listChanged: true } })).toEqual({ toolsListChanged: true });
+        // resources.subscribe gates resourceSubscriptions; resources.listChanged gates resourcesListChanged.
+        expect(honoredSubset(requested, { resources: { subscribe: true } })).toEqual({ resourceSubscriptions: ['file:///a'] });
+        expect(honoredSubset(requested, { resources: { listChanged: true } })).toEqual({ resourcesListChanged: true });
+        // No relevant capability advertised → empty.
+        expect(honoredSubset(requested, {})).toEqual({});
+        // Omitted capabilities → requested set honored as-is (back-compat).
+        expect(honoredSubset(requested)).toEqual(requested);
+    });
 });
 
 describe('serverEventToNotification', () => {