What are ttlMs and cacheScope in MCP?

The short answer

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "tools": [ … ]
  }
}

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "resultType": "complete",
    "tools": [ … ],
    "ttlMs": 60000,
    "cacheScope": "public"
  }
}

Both fields are required, not optional hints — omitting either is a MUST-level failure. Mechanically it is one of the smallest changes in the revision, which is exactly why it is worth doing early: it is a few lines per list handler and it clears two of the most common validator failures.

Which methods carry them

Five, grouped by the spec under a new CacheableResult interface:

• tools/list
• prompts/list
• resources/list
• resources/read
• resources/templates/list

Note what is not on that list. tools/call does not carry caching metadata — a tool invocation is an action, not a lookup, and the spec does not invite intermediaries to cache one. The five above are the discovery and read surface, which is the part a client calls repeatedly with identical arguments.

ttlMs in detail

It is a hint, not a contract. A client may re-fetch sooner, and it may not cache at all. What the server is promising is narrower: that reusing the result for up to this long is a reasonable thing to do.

// Tools are defined in code and ship with the deploy —
// they cannot change between requests to the same build.
{ "ttlMs": 3600000, "cacheScope": "public" }     // 1 hour

// Resource list assembled from a database that users write to.
{ "ttlMs": 5000, "cacheScope": "private" }       // 5 seconds

// A list you cannot reason about — be conservative, not clever.
{ "ttlMs": 0, "cacheScope": "private" }          // no reuse

cacheScope in detail

The value set is closed. "public" and "private" are the only two valid values — not "no-cache", "none", true, or any HTTP Cache-Control token borrowed by analogy. MCP-CAC-003 exists because that borrowing is a real and easy mistake for anyone who has written HTTP caching before.

Why this arrived in the same revision as statelessness

The two changes are one design. Removing sessions means a client can no longer learn a tool list once during a handshake and hold it for the life of a connection — it re-asks, potentially on every request, and each of those calls is a round trip that the legacy protocol did not have to make.

Caching is what pays for that. And caching only became sound because of statelessness: once list endpoints stopped varying per connection, two identical requests genuinely have the same answer, so an intermediary can serve one from the other.

Read the two rules together and the dependency is explicit. If your tools/list still varies per connection — the failure MCP-STL-008 catches — then no cacheScope value you write is honest, because the premise the field rests on is false.

The public/private mistake worth avoiding

This is the one place in the caching rules where getting it wrong is a security problem rather than a performance one.

MCP-CAC-005 is the rule that flags this, and it is the only caching rule marked security-relevant. It is graded as a warning rather than a failure because detecting personalisation from outside is inference, not certainty — but a security-relevant finding caps the report grade at D regardless.

The 5 caching rules we check

Frequently asked

Related