MCP server: list-change notifications are lost for clients that negotiate 2026-07-28 (no subscriptions/listen) #1383

Summary

When a client negotiates protocol revision 2026-07-28 (via server/discover), a StdioMcpServer cannot deliver tool or prompt list changes to it. A server that proxies MCP servers with dynamic tool discovery therefore stops working for those clients. In that pattern, an upstream adds tools during a tools/call and emits notifications/tools/list_changed, but the client never re-lists, so the new tools are never offered to the model.

Details

• In 2026-07-28, list-change notifications are only delivered on a subscriptions/listen stream that the client opened with toolsListChanged: true.
  • Each notification on that stream is tagged with io.modelcontextprotocol/subscriptionId.
  • notifications/subscriptions/acknowledged comes first.
  • The spec says "the server MUST NOT send notification types the client has not explicitly requested" (see also Tools › List Changed Notification).
• mcp-server does not implement subscriptions/listen (it returns -32601). McpDomainOperations.discoverCapabilities therefore correctly advertises tools: {} and prompts: {} without listChanged, as planned in MCP server: support protocol revision 2026-07-28 (stateless / modern era) #1337.
• McpCatalog.onRemoteNotification still writes the upstream's untagged notifications/tools/list_changed to the transport, regardless of the negotiated revision. A client that negotiated 2026-07-28 ignores it, because the capability was not advertised and it has no subscription.
• The same clients work against the same server when it only offers the handshake versions. They fall back to initialize, the server advertises tools.listChanged: true, and the forwarded notification triggers a re-list.

Reproduction

1. Build a StdioMcpServer with an HttpMcpClient remote. On tools/call discover, the remote adds a tool and writes notifications/tools/list_changed followed by the result into the SSE response.
2. The client sends server/discover with _meta["io.modelcontextprotocol/protocolVersion"] = "2026-07-28". The result lists 2026-07-28 first, and capabilities.tools has no listChanged.
3. The client calls discover. The server writes an untagged list_changed and the result. A 2026-07-28 client does not re-list, and tools/call for the new tool fails with -32602 No such tool until something else triggers a tools/list.
4. If listChanged: true is advertised, a client sends subscriptions/listen with {"notifications":{"toolsListChanged":true,"promptsListChanged":true}} and receives -32601.

Proposed fix

• Short term (PR to follow): add an opt-in protocolVersions(...) to McpEngine.Builder and StdioMcpServerBuilder, so a server that relays list changes can serve the handshake versions only. A client that prefers 2026-07-28 then receives -32022 with the supported list from server/discover, falls back to initialize, and keeps receiving list changes.
• Longer term: implement subscriptions/listen on stdio and advertise listChanged from server/discover once it is available. Points that came up while looking at this:
  • Use a subscription registry owned by the connection and keyed by the listen request id, preserving the id's JSON type.
  • Send the acknowledgement strictly before any notification on that subscription.
  • Handle notifications/cancelled for the listen id, and send the completion result on graceful shutdown.
  • Define explicit behavior when handshake and stateless requests share one stdio connection; today there is one mutable session version.
  • Install notification callbacks for upstreams that are reached through 2026-07-28; today they are installed only during initialize.
  • HTTP needs a streaming POST response before it can support this.
  • Separately: do not send untagged list-change notifications to 2026-07-28 clients that have not subscribed.