Merge pull request #495 from koic/subscriptions_listen

Serve the `subscriptions/listen` notification stream per SEP-2575

Author: koic

README.md

@@ -54,6 +54,13 @@ It implements the Model Context Protocol specification, handling model context r
   and the Streamable HTTP transport serves them on a sessionless single-exchange path. On the client, `MCP::Client#connect` negotiates
   the lifecycle automatically by default (probe `server/discover`, fall back to the `initialize` handshake), `connect(mode: :modern)` skips
   the handshake entirely, `connect(mode: :legacy)` forces the classic handshake, and `MCP::Client#discover` exposes the raw discovery result
+- `subscriptions/listen` - Long-lived notification subscription stream (MCP 2026-07-28, SEP-2575), replacing the legacy HTTP GET listening stream:
+  the client opts in via the `notifications` filter (`toolsListChanged` / `promptsListChanged` / `resourcesListChanged` / `resourceSubscriptions`),
+  the server acknowledges the honored subset with `notifications/subscriptions/acknowledged` as the first stream message,
+  and every delivered notification carries the correlating `io.modelcontextprotocol/subscriptionId` in `_meta`. Served on the Streamable HTTP modern path;
+  stdio answers `-32601`. Concurrent streams are capped by `max_listen_subscriptions:` (default 1000), and each stream receives an SSE keepalive
+  comment frame every `listen_keepalive_interval:` seconds (default 15) so a dropped connection frees its slot; pass `listen_keepalive_interval: nil`
+  when an upstream proxy already keeps the stream alive
 - Multi round-trip `input_required` results (MCP 2026-07-28, SEP-2322): a `tools/call`, `prompts/get`, or `resources/read` handler that
   opts in to `server_context:` may return `MCP::Server::InputRequiredResult.new(input_requests:, request_state:)` to ask the client for
   additional input (`elicitation/create`, `sampling/createMessage`, or `roots/list` shapes) instead of performing a server-initiated request,

conformance/server.rb

@@ -667,6 +667,34 @@ def call(server_context:, **_args)
         end
       end
     end
+
+    class TestTriggerToolChange < MCP::Tool
+      tool_name "test_trigger_tool_change"
+      description "A diagnostic tool that broadcasts notifications/tools/list_changed to listen streams (SEP-2575)"
+
+      class << self
+        # The broadcast alone exercises the `subscriptions/listen` delivery, so no actual
+        # tool-list mutation is needed, matching the suite's TypeScript reference fixture.
+        def call(server_context:, **_args)
+          server_context.notify_tools_list_changed
+
+          MCP::Tool::Response.new([MCP::Content::Text.new("Mutation triggered").to_h])
+        end
+      end
+    end
+
+    class TestTriggerPromptChange < MCP::Tool
+      tool_name "test_trigger_prompt_change"
+      description "A diagnostic tool that broadcasts notifications/prompts/list_changed to listen streams (SEP-2575)"
+
+      class << self
+        def call(server_context:, **_args)
+          server_context.notify_prompts_list_changed
+
+          MCP::Tool::Response.new([MCP::Content::Text.new("Mutation triggered").to_h])
+        end
+      end
+    end
   end
 
   module Prompts
@@ -907,6 +935,8 @@ def build_server
           Tools::TestInputRequiredResultCapabilities,
           Tools::TestStreamingElicitation,
           Tools::TestLoggingTool,
+          Tools::TestTriggerToolChange,
+          Tools::TestTriggerPromptChange,
         ],
         prompts: [
           Prompts::TestSimplePrompt,

lib/mcp/methods.rb

@@ -7,6 +7,10 @@ module Methods
     LOGGING_SET_LEVEL = "logging/setLevel"
     # Sessionless capability discovery (MCP 2026-07-28 draft, SEP-2575).
     SERVER_DISCOVER = "server/discover"
+    # Long-lived notification subscription stream (MCP 2026-07-28, SEP-2575),
+    # replacing the legacy HTTP GET listening stream. Served at the transport layer
+    # (Streamable HTTP modern path); transports without streaming support answer `-32601`.
+    SUBSCRIPTIONS_LISTEN = "subscriptions/listen"
 
     PROMPTS_GET = "prompts/get"
     PROMPTS_LIST = "prompts/list"
@@ -50,6 +54,9 @@ module Methods
     NOTIFICATIONS_PROGRESS = "notifications/progress"
     NOTIFICATIONS_CANCELLED = "notifications/cancelled"
     NOTIFICATIONS_ELICITATION_COMPLETE = "notifications/elicitation/complete"
+    # First message on a `subscriptions/listen` stream (SEP-2575): reports the subset
+    # of requested notification types the server agreed to honor.
+    NOTIFICATIONS_SUBSCRIPTIONS_ACKNOWLEDGED = "notifications/subscriptions/acknowledged"
 
     class MissingRequiredCapabilityError < StandardError
       attr_reader :method

lib/mcp/request_envelope.rb

@@ -16,6 +16,10 @@ class RequestEnvelope
     # Optional per-request log level, replacing the `logging/setLevel` RPC in the modern lifecycle.
     # Deprecated as of 2026-07-28 (SEP-2577) but still part of the wire format.
     LOG_LEVEL_META_KEY = "io.modelcontextprotocol/logLevel"
+    # Notification-side reserved key (SEP-2575): correlates a notification delivered on
+    # a `subscriptions/listen` stream (and the stream's closing result) with the JSON-RPC id of
+    # the `subscriptions/listen` request that opened it. Not part of the request envelope triple.
+    SUBSCRIPTION_ID_META_KEY = "io.modelcontextprotocol/subscriptionId"
 
     # Result-side counterpart of the request envelope: the server's identity rides in
     # the result's `_meta` as an optional stamp, not as a top-level field, since the SEP was

lib/mcp/server.rb

@@ -941,7 +941,7 @@ def validate_initialize_params!(params)
     def discover(_request)
       {
         supportedVersions: Configuration::SUPPORTED_MODERN_PROTOCOL_VERSIONS,
-        capabilities: capabilities,
+        capabilities: discover_capabilities,
         instructions: instructions,
         _meta: { RequestEnvelope::SERVER_INFO_META_KEY => server_info },
       }.compact.merge(
@@ -953,6 +953,21 @@ def discover(_request)
       )
     end
 
+    # Capabilities as advertised by `server/discover`. In the modern lifecycle, `listChanged` and `subscribe` flags
+    # promise delivery over `subscriptions/listen` streams, so they are stripped when the transport does not serve that RPC
+    # (e.g. stdio), matching the Python SDK's era-aware capability derivation.
+    def discover_capabilities
+      return capabilities if @transport.respond_to?(:serves_subscriptions_listen?) && @transport.serves_subscriptions_listen?
+
+      capabilities.each_with_object({}) do |(name, value), stripped|
+        stripped[name] = if value.is_a?(Hash)
+          value.reject { |flag, _| ["listChanged", "subscribe"].include?(flag.to_s) }
+        else
+          value
+        end
+      end
+    end
+
     def configure_logging_level(request, session: nil)
       if capabilities[:logging].nil?
         raise RequestHandlerError.new("Server does not support logging", request, error_type: :internal_error)