Add ttlMs and cacheScope to cacheable result records (SEP-2549)#1062
Open
aboullaite wants to merge 2 commits into
Open
Add ttlMs and cacheScope to cacheable result records (SEP-2549)#1062aboullaite wants to merge 2 commits into
aboullaite wants to merge 2 commits into
Conversation
added 2 commits
July 16, 2026 16:06
The draft spec introduces TTL caching hints on list and read results. This adds the optional ttlMs (Integer) and cacheScope (CacheScope enum) fields to ListToolsResult, ListPromptsResult, ListResourcesResult, ListResourceTemplatesResult, and ReadResourceResult, following the wire-record evolution rules in CONTRIBUTING.md. Purely additive, schema-layer only: no server or client behavior changes. Server-side TTL configuration hooks are deferred to modelcontextprotocol#578.
The draft spec requires cacheable results to carry ttlMs and cacheScope on the wire. Other SDKs (Go, Python, TypeScript) all stamp defaults after handlers return: ttlMs=0 (immediately stale) and cacheScope=public. This adds the same default stamping in McpAsyncServer and McpStatelessAsyncServer for all five cacheable result types. For list results the defaults are set at the build site. For ReadResourceResult, which is built by user handlers, a withCacheDefaults helper stamps missing fields while preserving any values the handler set explicitly.
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.
Add ttlMs and cacheScope to cacheable result records (SEP-2549)
Motivation and Context
SEP-2549 introduces TTL caching hints so clients and intermediaries (gateways, proxies) can cache list and read results without re-fetching on every request. The draft spec adds two fields to cacheable result types:
ttlMs(integer, >= 0): how long in milliseconds the client may consider the response fresh, analogous to HTTPCache-Control: max-agecacheScope(enum:"private"/"public"): whether the response may be shared across authorization contexts, analogous to HTTPCache-Control: privatevspublicThis PR adds the schema fields and server-side default stamping. The server now emits
ttlMs=0(immediately stale) andcacheScope="public"on all cacheable responses. Server-side configuration hooks for user-defined TTLs are intentionally left out following @Kehrlann's note that those belong with the repositories refactor in #578 (and the related #1034).Towards #1009
How Has This Been Tested?
UT + IT
Breaking Changes
None. Both fields are optional (nullable), existing constructors are preserved as
@Deprecatedoverloads.Types of changes
Checklist
Additional context
Remaining work for full #1009 coverage (follow-up PRs):
ResourceRepository,ToolsRepository, ... ) #578)