Testing MCP List-Changed Notifications and Resource Subscriptions

MCP resource subscription testing should prove convergence, not merely observe a notification in a log. The client must negotiate the feature, establish a subscription to the intended URI, survive mutations and transport races, refresh from the authoritative server, and end with a catalog and content view that matches policy.

The MCP resources specification defines two independent optional capabilities. listChanged covers changes to the set of available resources; subscribe covers updates to an individual resource. That distinction controls the oracle, the message expected, and the recovery request.

Separate catalog events from content events

Start with two state models. The catalog model is the complete authorized set of resource descriptors returned by every page of resources/list. The content model maps a resource URI to the contents returned by resources/read. Adding, removing, or changing visibility of a resource affects the catalog. Editing the body behind an existing URI affects content.

For a catalog mutation, expect notifications/resources/list_changed only when the server declared resources.listChanged. The notification has no resource list in its payload, so the client must list again. For a subscribed content mutation, expect notifications/resources/updated with the URI. The client must read that URI again if it needs fresh contents.

Metadata changes need an explicit product classification. If a title, MIME type, or annotation change is exposed through listing, document whether it counts as catalog change. The protocol names the signal but does not define every backend mutation. Your suite should enforce the server's published behavior without pretending an unstated rule is universal.

Negotiate before entering the operation phase

The MCP lifecycle specification makes initialization the first interaction, exchanges capabilities there, and requires the client to send notifications/initialized after a successful response. Build four capability fixtures: neither option, subscribe only, listChanged only, and both.

Assert that a client never sends resources/subscribe when subscribe is absent. Assert that it does not wait for list-change events when listChanged is absent; it needs another refresh policy if current catalog data matters. Also inject a server that advertises a capability but rejects its operation, because declaration and implementation can drift.

Messages arriving before operation are a lifecycle violation, not proof that subscriptions work. Capture initialize request, initialize response, initialized notification, subscription request and response, then mutation. Stable ordering in the harness prevents a false pass where the mutation occurred before the server registered the subscription.

Build an authoritative state oracle

Give the test environment a control plane that can create, edit, revoke, restore, and delete resources without using the client path under test. Each control operation should return a mutation ID and the committed server-side state. That ID is test evidence, not a field expected in MCP notifications.

List all pages when calculating the catalog. A first-page-only assertion will miss additions beyond the page boundary, duplicate URIs across pages, cursor loops, and removals that shift page composition. Canonicalize descriptors structurally while preserving URI strings exactly; resource URIs are identifiers, not casual text.

For content, compare media type and the correct text or binary representation. Avoid using lastModified alone as the oracle because it is an optional annotation and timestamps can collide. A test-only content hash calculated after a successful authorized read is useful, provided binary decoding follows the protocol and sensitive bodies are not written to reports.

Control subscription setup and mutation timing

A reliable happy-path case follows a barrier sequence: initialize, verify capability, list, subscribe, await the successful subscribe response, mutate, await the matching update signal, read, and compare. Never replace these barriers with arbitrary sleeps.

This TypeScript harness sketch records causality while keeping transport details behind an adapter:

type ObservedEvent = { method: string; uri?: string; receivedAt: number }

async function verifySubscribedUpdate(uri: string): Promise<void> {
  await mcp.initialize()
  expect(mcp.serverCapabilities.resources?.subscribe).toBe(true)
  await mcp.subscribe(uri)

  const mutation = await controlPlane.replaceText(uri, 'revised fixture')
  const event: ObservedEvent = await inbox.next(
    (item) => item.method === 'notifications/resources/updated' && item.uri === uri,
  )

  const content = await mcp.read(uri)
  expect(content.text).toBe(mutation.committedText)
  expect(event.receivedAt).toBeGreaterThanOrEqual(mutation.acceptedAt)
}

The timestamps help diagnose the harness; they do not establish a protocol-wide latency limit. Set an environment-specific deadline and label it as such. A timeout should report whether subscription succeeded, mutation committed, any event arrived, and the final read already contained the change.

Test list membership through full reconciliation

Exercise add, remove, and visibility changes. After each list_changed notification, fetch every page and compare URI sets plus relevant descriptors. On removal, also call resources/read for the old URI and verify the server's documented not-found or authorization behavior. The resources specification identifies JSON-RPC -32002 for resource not found, but a visibility revocation may intentionally use a different security-preserving response.

Run mutations in bursts. A server may choose to coalesce invalidation work under its application contract; the client should still converge after re-listing. Do not assert one notification per database row unless the server explicitly promises that cardinality. Instead, define a quiet-window or mutation-barrier mechanism in the test environment, then assert final catalog state and bounded refresh amplification.

Pagination races deserve dedicated cases. Add a resource between page requests, remove the cursor boundary item, and change authorization while traversal is active. Decide whether the client restarts listing, accepts a documented snapshot model, or retries after an invalid cursor. The final assertion must not combine pages from incompatible catalog generations without detection.

Expose subscribe-mutate races deliberately

Race one mutates just before the subscribe request reaches the server. The client should establish current content with an initial read or another documented synchronization strategy; waiting only for future events can leave it stale forever. Race two mutates while subscribe is in flight. Race three mutates after subscribe acknowledgement but before the test starts listening. Buffer events before triggering the mutation so the harness cannot create its own loss window.

Run two rapid writes to one URI and concurrent writes to different URIs. Check that a URI-specific event never causes the client to refresh a different protected resource. If the application de-duplicates refreshes, assert it eventually reads the latest state, not that every intermediate value appears.

The base messages do not carry sequence numbers or content versions. If the product adds revision metadata through an extension, test its negotiation and fallback separately. Without such a contract, exact ordering claims belong to the transport or implementation, not to generic MCP conformance.

Treat notifications as invalidation signals

An update event says a subscribed URI changed. It is not the changed content and it does not authorize a read. The client must call resources/read using its current session and credentials. This preserves server-side validation, access control, and content encoding.

Test revocation between subscription and refresh. The event must not leak content, and the subsequent read must enforce current permissions. Test deletion after update, update after deletion, and a URI that becomes visible to one user while remaining hidden from another. Notification routing needs the same tenant and identity isolation as direct reads.

Make refresh handlers idempotent. Duplicate events should not duplicate user-visible records or recursively create writes. A refresh failure should be classified as transient dependency error, terminal authorization denial, not found, malformed content, or protocol failure. Each class needs a bounded retry or terminal policy.

Reconnect without assuming session continuity

Drop the connection before subscription acknowledgement, after acknowledgement, during mutation, and after event receipt but before refresh. Re-run initialization on the new session, inspect newly negotiated capabilities, rebuild the catalog, and re-establish desired subscriptions. The server may have changed capabilities while disconnected.

Do not assume a subscription survives process restart or transport replacement unless your implementation explicitly guarantees and tests durable subscription state. Store desired URIs in the client application if resubscription is required, but reauthorize each one. A previously visible URI may no longer be permitted.

Include duplicate reconnect attempts and half-open connections. There must be one active refresh owner per logical client view, or deliberate fan-out with de-duplication. Record connection ID, negotiated protocol version, capability set, subscription attempt, URI, and terminal response without logging protected resource contents.

Use an explicit failure model

Capture event counts, refresh counts, end-to-end convergence time, and unresolved states as separate measures. Tail behavior matters: a low median can hide rare clients that never reconcile. Any deadline in the suite is an illustrative product SLO until the owning team approves it.

Execute the release checklist

1. Test all four combinations of subscribe and listChanged capability flags after a valid lifecycle handshake.
2. Establish complete paginated catalog and content oracles under each relevant identity.
3. Verify add, remove, visibility, metadata, text, and binary mutations against the correct event type.
4. Place barriers around subscribe acknowledgement, mutation commit, event capture, and authoritative refresh.
5. Inject duplicate, missing, delayed, burst, cross-URI, pagination, authorization, and reconnect failures.
6. Assert eventual authorized state, not a convenient notification count, while tracking refresh amplification and tail convergence.
7. Block release on cross-tenant events, permanent stale states, lifecycle misuse, unbounded retry, or a claimed capability that cannot complete its operation.

The decisive test is simple to state: after controlled change and realistic failure, every authorized client view converges and every unauthorized client learns nothing. The work lies in proving each event boundary rather than confusing message arrival with consistency.