Skip to main content
Subscriptions let a client keep a live subscriptions/listen request open and receive list or resource invalidations. After an invalidation, the client reads the affected resource again to obtain current content. Delivery is listener-bound and non-durable. The stateless HTTP transport does not store subscriptions in a session, queue missed events, or provide replay after a listener disconnects.

Publish resource changes

Define a resource with a stable URI, update its backing data, and publish the appropriate invalidation:
notifyResourceUpdated(uri) tells listeners that the representation at one URI changed; it does not send the new body. Use notifyResourcesChanged() when the discoverable resource or template list changes:
The related helpers are notifyToolsChanged() and notifyPromptsChanged().

Design for missed events

Treat notifications as cache invalidations:
  • Keep the resource itself authoritative.
  • Make reads safe to repeat.
  • Do not depend on every intermediate invalidation being delivered.
  • Store durable job state, audit history, and workflow progress outside the subscription stream.
Use request-scoped custom notifications for status emitted during one active tool call. See Notifications.

Test a live listener

Run the maintained notifications example:
Connect a current MCP client that supports subscriptions/listen, keep the listener request open, and read example://status. Call publish-changes, verify that the listener receives the resource invalidation, and read the resource again. Disconnect the listener and verify that later events are not replayed when a new listener connects.