Skip to content

Implement SEP-2549: TTL for List Results #2191

Closed

Description

@felixweinberger

This is a tracking issue for implementation of SEP-2549.

Activity

  1. mattzcarey commented on May 29, 2026

    @mattzcarey
    Member

    Status — SEP-2549 (TTL for List Results / ttlMs + cacheScope)

    Track: B — independent, starts now.
    Spec: seps/2549-TTL-for-list-results.md · merged 2026-05-15

    What's done

    Outstanding (acceptance criteria, summary)

    • R-2549-1 (wire): Server MUST include ttlMs (≥0) and cacheScope ("public" | "private") on tools/list, prompts/list, resources/list, resources/templates/list, resources/read results
    • R-2549-2: Client SHOULD refetch on next access after ttlMs expires (MAY serve stale on refetch error)
    • R-2549-4: list_changed notifications still delivered if subscribed — ttl is a hint, not a replacement
    • R-2549-8: Same cacheScope on every page of a paginated list response
    • R-2549-10 (sdk): Polling helpers MUST apply jitter + backoff (spec text and SEP MD differ on MUST vs SHOULD — caching.mdx wins per spec page)
    • R-2549-11: Receiving list_changed / resources/updated invalidates the client cache regardless of remaining TTL
    • R-2549-12: Absent ttlMs on a response → treat as 0 (immediately stale) — BC with pre-2549 servers
    • R-2549-13: Negative ttlMs → treat as 0
    • R-2549-14: Cursor invalid (-32602 on next-page fetch) → discard all cached pages, re-fetch from page 1
    • R-2549-3 (guidance): Per-page ttlMs; freshness lives on ListToolsResult, not on Tool
    • R-2549-7 (security MUST NOT): Shared caches MUST NOT serve cacheScope: "private" to a different user — keyed on auth principal if the SDK ships a shared-cache helper

    Suggested phasing

    1. Rename and reshape feat(core,client,server): ttl on list results (SEP-2549) #2070's ttl: number → ttlMs: number + add cacheScope: 'public' | 'private' on a shared CacheableResult interface
    2. Server: populate from McpServerOptions.{listTtlMs, defaultCacheScope}
    3. Client cache: TTL-based staleness + list_changed/resources/updated invalidation hooks
    4. Pagination semantics: page-level TTL, cursor-invalid → discard
    5. Polling helper (if shipped): jitter + exponential backoff

    Coordination

    • Pure result-shape change, no cross-track dependencies. Can land on main ahead of the v2 stack and be rebased.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions