docs: document subscriptions/listen and CacheableResult in draft learn and client pages#3068
Draft
claude[bot] wants to merge 4 commits into
Draft
docs: document subscriptions/listen and CacheableResult in draft learn and client pages#3068claude[bot] wants to merge 4 commits into
claude[bot] wants to merge 4 commits into
Conversation
… 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Den Delimarsky · Slack thread
Readers of the draft learn pages previously saw resource updates explained through
resources/subscribeand tool list examples with no caching hints. The server concepts and architecture pages now walk through thesubscriptions/listenflow, from the filtered request and its required_metafields to the acknowledgment and the tagged update notifications. The architecture page's tool list example and the client best practices page now coverresultTypetogether with thettlMsandcacheScopecaching 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/subscribeand 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
Checklist
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