[Server][Schema] SEP-2549: ttlMs and cacheScope on list/read results

[chr-hertel]

Implements SEP-2549 for the MCP Spec 2026-07-28 release.

Tracked by umbrella #336. Fully additive, non-breaking.

Spec summary

Adds ttlMs (freshness lifetime) and cacheScope (who may cache: private, shared, etc.) to results of tools/list, prompts/list, resources/list, resources/read, and resources/templates/list. Coexists with existing notifications/list_changed.

PHP SDK changes

• src/Schema/Result/ListToolsResult.php, ListPromptsResult.php, ListResourcesResult.php, ListResourceTemplatesResult.php, ReadResourceResult.php — add optional ttlMs: ?int and cacheScope: ?string fields.
• Add a CacheScope enum under src/Schema/Enum/.
• src/Capability/Registry/Registry.php and list handlers (src/Server/Handler/Request/List*Handler.php) — accept TTL/scope config (via Builder or per-capability attributes).
• src/Server/Builder.php — add global defaults like setListTtlMs(int), setListCacheScope(CacheScope).
• Consider new #[Cacheable(ttlMs: ..., scope: ...)] attribute under src/Capability/Attribute/.
• Client-side honoring is optional and can be a follow-up.

Related

• Umbrella [2026-07-28] Transport & observability headers/metadata #336