fix(server): default missing cache hints for 2026-07-28 peers

[DaleSeo]

Motivation and Context

Protocol version 2026-07-28 requires ttlMs and cacheScope on every complete tools/list, prompts/list, resources/list, resources/templates/list, and resources/read result. The caching utility describes this requirement. The #[tool_handler] and #[prompt_handler] macros already add these hints, but there is no equivalent macro for resources. As a result, hand-written resource handlers, which often build results with ..Default::default() or ReadResourceResult::new, send results without the required hints. Strict clients reject them.

The fix follows the existing strip_result_type_for_legacy_peer step. A new ServerResult::fill_missing_cache_hints runs for modern peers in the same place where resultType is stripped for legacy peers. Missing hints default to the most conservative values, ttlMs: 0 (immediately stale) and cacheScope: "private", matching DiscoverResult::new. Any hints set by the handler, including the macros' public scope, are left unchanged. Legacy peers are unaffected.

Before responding to a peer using protocol version 2026-07-28 or newer, the server handler now fills in any missing SEP-2549 caching hints (ttlMs and cacheScope) on cacheable results.

How Has This Been Tested?

Added tests

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

[rolandd]

definitely a needed fix

[rolandd]

Thanks for this fix - I just ran into this issue with atuin mcp (https://github.com/atuinsh/atuin) in claude, where the two sides negotiate 2026-07-28 protocol version and then the connection fails because of missing ttlMs / cacheScope.

Change looks good overall, only comment is that atuin has a list_tools() that doesn't use the #[tool_handler] macro, I wonder if it's worth also adding test coverage for manual list_tools() and list_prompts() handlers too?

[DaleSeo]

Thanks for testing it, @rolandd! Makes sense. I added a test server with hand-written list_tools() and list_prompts() handlers.

[alexhancock]

Shouldn't this be driven by something referencing sep 2549?

https://modelcontextprotocol.io/seps/2549-TTL-for-list-results

Also, how do we feel generally about referencing certain sep numbers in the code? I know this one was pre-existing but it feels like we should consider modeling things based on a more generic description of the relevant functionality vs the SEP ids. I can see benefits to either approach. What do you think?

[DaleSeo]

@alexhancock Good catch. All three gates depend on the peer's protocol version, not on a specific SEP. I renamed the check to is_2026_07_28_or_later.

I'd keep the SEP number in doc comments, but not in function or variable names. Happy to clean up the existing ones in a follow-up. :)