MCP Resource Subscriptions and Change Notifications

MCP resource subscriptions let a client ask a server to say when a specific resource changes. In the 2026-07-28 spec, the client does this by opening one long-lived subscriptions/listen request that names the resource URIs it cares about. The server then sends notifications/resources/updated on that stream whenever one of them changes.

Status in the 2026-07-28 spec: core, redesigned. The old resources/subscribe and resources/unsubscribe methods were replaced by subscriptions/listen in this release. They do not appear in the deprecated features registry; the changelog lists them as replaced.

The same stream also carries "the list changed" alerts for tools, prompts and resources. This page is based on the Subscriptions page and the Resources page, checked on 28 October 2026.

What subscriptions are

A subscription is a standing request: "tell me when this changes." Without it, a client would have to poll, re-reading data on a timer.

MCP has four kinds of change notification. The subscriptions/listen request has a filter field for each:

All fields are optional. Leaving one out means "don't send me that type."

Why it was redesigned

Before 2026-07-28, resource updates used a resources/subscribe call. On Streamable HTTP, clients could also open a standalone GET stream for server-initiated messages, and servers could assign a session ID, per the Streamable HTTP page. This release removed all three.

The 2026-07-28 release made MCP stateless, as covered in why MCP became stateless. The changelog describes the replacement as "a single long-lived POST-response stream for opted-in server-to-client change notifications." Because the subscription is just an open request, nothing has to be stored between requests.

How it works

Step 1: open the stream

The client sends a subscriptions/listen request with a notifications filter. This is the spec's example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscriptions/listen",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "ExampleClient", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "notifications": {
      "toolsListChanged": true,
      "resourceSubscriptions": ["file:///project/config.json"]
    }
  }
}

Step 2: the server acknowledges

The server MUST send notifications/subscriptions/acknowledged first. Its notifications field shows what the server agreed to honor, which may be less than requested. The client SHOULD compare the two and handle missing types gracefully.

Step 3: notifications arrive

Each notification carries io.modelcontextprotocol/subscriptionId in _meta. Its value is the JSON-RPC ID of the listen request, 1 in this example. A client may run several subscriptions at once and uses this ID to tell them apart. On stdio it MUST use it, because everything shares one channel.

After a notifications/resources/updated, the client typically sends resources/read again to get the new contents.

Step 4: closing

A subscription ends when the client cancels it, the server tears it down, or the transport closes. On HTTP, the client cancels by closing the stream. On stdio, it sends notifications/cancelled. A server that ends a subscription on purpose SHOULD first send a normal response to the listen request, so the client can tell a clean close from a dropped connection.

The server's side

The resources capability has a subscribe flag. In 2026-07-28 it means the server supports resource-specific update notifications through the resourceSubscriptions filter. The listChanged flag covers list changes. A server may support either, both or neither.

Two notification types do not use this stream. The changelog says request-scoped notifications, such as notifications/progress and notifications/message, flow on the response stream of the request they belong to.

What changed across spec versions

Migration checklist

1. Replace resources/subscribe calls with one subscriptions/listen request that lists all URIs in resourceSubscriptions.
2. The spec describes no call to edit a filter. To watch different URIs, open a new subscription and cancel the old one. Each is identified by its own request ID.
3. Handle the acknowledgment and check which types the server accepted.
4. Route notifications by subscriptionId, not by connection.
5. On stdio, re-send subscriptions/listen after any reconnect. On HTTP, the spec says a client MAY treat a drop without a final response as a reason to reconnect.

For transport details, see MCP Streamable HTTP transport.

Common mistakes

1. Sending notifications nobody asked for. The server MUST NOT send types the client did not request.
2. Sending notifications before the acknowledgment. The acknowledgment must come first on each subscription.
3. Keeping subscription state across reconnects. The spec says the server holds none, so the client must re-subscribe.
4. Using the listen stream for progress updates. Progress goes on the response stream of the original request.
5. Treating notifications as data. An update notification only carries the URI. Read the resource again to get the new content.

Caching hints work alongside notifications. The caching page says the two "can coexist."

Next step

Resources and tools cover data and actions. Prompts cover reusable instructions. Read MCP prompts explained next, or return to the MCP specification reference.

Frequently asked questions