MCP tools/list ttlMs and cacheScope: what is safe to cache?

In the 2026-07-28 MCP revision, tools/list responses carry ttlMs and cacheScope, which tell a client how long a list may be reused and how widely. For Sume, the list you get is the one visible to your session: mutating and paid tools are hidden until the session has mcp:write or an API key. A cached list should therefore never be shared across sessions with different scopes.

What do ttlMs and cacheScope do?

The MCP release post says tools/list, prompts/list, resources/list and resources/read carry ttlMs and cacheScope. It gives the field names and where they appear; this page does not restate value semantics beyond that, so read the spec for the accepted values before you implement a cache.

Why does the Sume list differ by session?

Sume's tools_list tool lists every tool visible in this session, with safety metadata. Under OAuth mcp:read only, the session sees read-only tools; with mcp:write or an API key it sees the full hosted set. So two people on the same endpoint can legitimately see different lists.

How should a client cache it?

Key any cache by the credential or session, not by the URL alone, and drop it when the scopes change, for example after the user grants Write. The docs also tell agents to discover the live contract with tools_list and tools_schema rather than assume, so a stale list is the main risk. Sume's docs do not say the hosted server sends ttlMs or cacheScope today, so do not depend on them being present.

What does a stale list break?

A client holding a read-only list will not offer generate_image; one holding a write list may offer it to a session that now lacks the scope, and the call returns insufficient_scope. See tools and gates for the full split.

What if I do not cache at all?

Not caching is a valid choice. tools_list is a read-only tool, and the quickstart suggests calling it once after connecting to verify the session. A client that refreshes the list at session start and after any scope change stays correct without depending on cache fields.

The one thing to avoid is treating the first list as permanent. If Write is granted later, the visible set grows, and if the session is replaced by one with only read access, it shrinks.

Does the tool list ever differ from the docs?

Yes, and the docs say so: they tell agents to discover the live contract with tools_list and tools_schema and not to assume parity with the HTTP API. Live tool ids use underscores, such as tools_list and generate_image, and dotted aliases also work.

For a cache, that means the list is data about one session at one moment. Store it with the session identity, refresh it after a reconnect, and treat a call that returns insufficient_scope as a signal to refetch rather than as a bug.