docs: document subscriptions/listen and CacheableResult in draft learn and client pages by claude[bot] · Pull Request #3068 · modelcontextprotocol/modelcontextprotocol

claude · 2026-07-10T07:53:37Z

Requested by Den Delimarsky · Slack thread

Readers of the draft learn pages previously saw resource updates explained through resources/subscribe and tool list examples with no caching hints. The server concepts and architecture pages now walk through the subscriptions/listen flow, from the filtered request and its required _meta fields to the acknowledgment and the tagged update notifications. The architecture page's tool list example and the client best practices page now cover resultType together with the ttlMs and cacheScope caching fields.

Motivation and Context

Part of the docs preparation for the 2026-07-28 release. The learn pages still taught the old update flow, where resources/subscribe and a standalone GET stream delivered notifications, and the tool list examples predated the requirement that complete list and read results carry caching hints.

Closes #3041
Closes #3044

How Has This Been Tested?

Documentation-only change. Ran npm run check:docs, which passes after the changes. That covers the prettier format check, the MDX comment check, and the mint broken-links check. Prettier accepts the edited files as-is.

Breaking Changes

None.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

This bundle touches the draft architecture page, which other rc-high-priority bundle PRs also modify, so merge order may need care.

AI assistance disclosure: this PR, including the documentation changes and this description, was written primarily with AI assistance. The diff gets human review before merge.

Generated by Claude Code

… concepts The 2026-07-28 draft removes the resources/subscribe RPC. Update the resource protocol operations table to show subscriptions/listen and explain the resourceSubscriptions filter. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru

…itecture overview Rework the Real-time Updates step around the subscriptions/listen stream: clients opt in with a notifications filter (toolsListChanged), the server acknowledges the filter, and every notification carries io.modelcontextprotocol/subscriptionId in _meta. Add the required ttlMs and cacheScope fields to the example tools/list response with short field descriptions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru

Point the tool definition caching guidance at the spec's caching utility: ttlMs is a freshness hint that decides when to re-fetch, list_changed notifications invalidate early, and cacheScope private results must stay within one authorization context. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru

Add the required per-request _meta fields to the subscriptions/listen and follow-up tools/list examples, and add resultType: "complete" to the tools/list response that shows the ttlMs and cacheScope hints. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AfPKVFyxGAbS7i2f2vhT2G

localden

Second pass for spec alignment and prose cleanup, one em dash pair inline.

dsp-ant · 2026-07-21T02:34:04Z

- `"tools": {"listChanged": true}` - The server supports the tools primitive AND can send `tools/list_changed` notifications when its tool list changes
+- `"tools": {"listChanged": true}` - The server supports the tools primitive and can honor a `toolsListChanged` filter in `subscriptions/listen`. Clients that request this filter receive `notifications/tools/list_changed` when the tool list changes.
 - `"resources": {}` - The server also supports the resources primitive (can handle `resources/list` and `resources/read` methods)


Can we link to the subscription pages?

Done — the remaining unlinked subscriptions/listen mentions (architecture prose and the server-concepts resources section) now link to the subscriptions spec page as of 7d03123.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AfPKVFyxGAbS7i2f2vhT2G

pja-ant · 2026-07-22T16:21:43Z

+### Caching
+
+Each `tools/list` result carries `ttlMs` and `cacheScope` hints. Follow them as defined in the
+specification's [caching utility](/specification/draft/server/utilities/caching). In particular,
+treat a cached list as stale once a `list_changed` notification arrives, even before its TTL
+expires.
+


Suggested change

### Caching

Each `tools/list` result carries `ttlMs` and `cacheScope` hints. Follow them as defined in the

specification's [caching utility](/specification/draft/server/utilities/caching). In particular,

treat a cached list as stale once a `list_changed` notification arrives, even before its TTL

expires.

### Caching

All list (e.g.`tools/list`) ,as well as `server/discover` and `resources/read`, results carries `ttlMs` and `cacheScope` hints. Follow them as defined in the

specification's [caching utility](/specification/draft/server/utilities/caching). In particular,

treat a cached list as stale once a `list_changed` notification arrives, even before its TTL

expires.

Done in 8ba1088 — the Caching section now covers list results plus server/discover and resources/read, matching the caching utility's operation list.

pja-ant · 2026-07-22T16:24:56Z

+4. **Event-Driven**: The server decides when to send notifications based on internal state changes, making MCP connections dynamic and responsive.



Suggested change

4. **Event-Driven**: The server decides when to send notifications based on internal state changes, making MCP connections dynamic and responsive.

4. **Event-Driven**: The server decides when to send notifications based on internal state changes, making MCP connections dynamic and responsive.

5. **Best Effort**: There are no guarantees that every notification will be sent/received, particularly across transport reconnects. Clients should also rely on polling to preserve freshness of results.

Added the "Best Effort" bullet as suggested in 8ba1088.

…ns spec page Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018Ep4aMzUcNqroQQuXdiHKn

… note best-effort notification delivery Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018Ep4aMzUcNqroQQuXdiHKn

claude added 4 commits July 10, 2026 07:29

github-actions Bot added the documentation Improvements or additions to documentation label Jul 10, 2026

localden marked this pull request as ready for review July 14, 2026 06:37

localden requested review from a team as code owners July 14, 2026 06:37

localden self-assigned this Jul 14, 2026

localden added the rc-high-priority Related to an upcoming specification release and needs to be addressed with a high priority. label Jul 14, 2026

docs: carry _meta on the tools/list example and fix listChanged prose

733ef6a

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AfPKVFyxGAbS7i2f2vhT2G

localden reviewed Jul 18, 2026

View reviewed changes

Comment thread docs/docs/draft/learn/architecture.mdx Outdated

Comment thread docs/docs/draft/learn/architecture.mdx Outdated

docs: apply review wording for clientInfo and subscription acks

49c87a5

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AfPKVFyxGAbS7i2f2vhT2G

localden reviewed Jul 20, 2026

View reviewed changes

Comment thread docs/docs/draft/learn/architecture.mdx Outdated

docs: tighten tools list-change prose

fff44a6

localden mentioned this pull request Jul 20, 2026

docs: reflect the stateless protocol, server/discover, and session removal #3069

Open

9 tasks

dsp-ant requested changes Jul 21, 2026

View reviewed changes

docs: consolidate caching guidance and link subscription docs

76d4877

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AfPKVFyxGAbS7i2f2vhT2G

pja-ant reviewed Jul 22, 2026

View reviewed changes

claude added 2 commits July 22, 2026 16:25

docs: link remaining subscriptions/listen mentions to the subscriptio…

7d03123

…ns spec page Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018Ep4aMzUcNqroQQuXdiHKn

docs: broaden caching guidance to server/discover and resources/read;…

8ba1088

… note best-effort notification delivery Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018Ep4aMzUcNqroQQuXdiHKn

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: document subscriptions/listen and CacheableResult in draft learn and client pages#3068

docs: document subscriptions/listen and CacheableResult in draft learn and client pages#3068
claude[bot] wants to merge 10 commits into
docs/2026-07-28-releasefrom
claude/rc-server-concepts

claude Bot commented Jul 10, 2026

Uh oh!

Uh oh!

Uh oh!

localden left a comment

Uh oh!

Uh oh!

Uh oh!

dsp-ant Jul 21, 2026

Uh oh!

claude Bot Jul 22, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pja-ant Jul 22, 2026

Uh oh!

claude Bot Jul 22, 2026

Uh oh!

pja-ant Jul 22, 2026

Uh oh!

claude Bot Jul 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		4. Event-Driven: The server decides when to send notifications based on internal state changes, making MCP connections dynamic and responsive.

Uh oh!

Conversation

claude Bot commented Jul 10, 2026

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Uh oh!

Uh oh!

localden left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dsp-ant Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pja-ant Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

pja-ant Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants