Caching MCP listings: ttlMs, cacheScope, and subscriptions/listen
MCP 2026-07-28 lets servers tell clients how long tool, prompt, and resource listings stay fresh. Learn what ttlMs and cacheScope mean, when to use subscriptions, and how to set both in xmcp.
Since MCP 2026-07-28, a server tells clients how long a listing or a resource stays fresh with two fields on the result: ttlMs, a lifetime in milliseconds, and cacheScope, which says whether the result is the same for every caller. A client that honors them can skip tools/list on every turn. In xmcp you set them with cacheHints in xmcp.config.ts.
This guide follows the repository's cache hints example.
What are ttlMs and cacheScope?
They are freshness hints that ride on cacheable results:
| Field | Type | Meaning |
|---|---|---|
ttlMs | Non-negative integer | How many milliseconds a client may reuse the result |
cacheScope | "private" or "public" | private: for this caller only. public: the same for every caller |
The cacheable results are tools/list, prompts/list, resources/list, resources/templates/list, resources/read, and server/discover.
By default xmcp sends ttlMs: 0 and cacheScope: "private", which means "do not reuse this". Nothing is cached until you say a result is stable.
How do I set cache hints in xmcp?
Add cacheHints to the config, keyed by method:
A tools/list result from this server now ends with:
Unknown methods and fields fail the build, so a typo does not silently disable caching.
A resource can set its own hint for resources/read in its metadata:
A resource with no hint keeps the default. In the example, status://now returns the current time and is never reused:
| Result | ttlMs | cacheScope | Set by |
|---|---|---|---|
server/discover | 3600000 | public | cacheHints in the config |
tools/list, resources/list | 300000 | public | cacheHints in the config |
resources/read docs://pricing | 86400000 | public | The resource's cacheHint |
resources/read status://now | 0 | private | Default |
A per-resource hint overrides cacheHints["resources/read"] field by field. A ttlMs or cacheScope returned directly by a handler or middleware takes precedence over both.
When is a result public?
When it is identical for every caller of the server. Use private, the default, in these cases:
- An
authorizepolicy or other auth-dependent middleware hides components from some callers. - A resource's contents depend on who is reading it.
Marking a per-caller result public tells clients it can be shared across callers. When in doubt, keep it private and set only a ttlMs.
How long should the TTL be?
Match it to how often the result changes:
| Result | Changes when | Reasonable hint |
|---|---|---|
| Listings on a server with a fixed roster | You deploy | Minutes |
| A resource updated on a schedule | The schedule runs | Up to the schedule interval |
| A resource with live data | Constantly | 0, the default |
An xmcp server's components come from files, so its roster is fixed for the life of a build and a listing only changes when you deploy. A TTL of a few minutes bounds how long a client can hold a stale listing after a deploy.
Tool order matters for caching too. The 2026-07-28 revision says servers should return tools/list in a deterministic order, because a stable listing also keeps the model's prompt cache warm.
What is subscriptions/listen?
It is the push alternative. A 2026-07-28 client opens one long-lived subscriptions/listen stream and chooses the notifications it wants: toolsListChanged, promptsListChanged, resourcesListChanged, or resourceSubscriptions. It replaces resources/subscribe and the standalone GET stream from earlier revisions.
Cache hints and subscriptions answer the same question, when to refetch, in different ways:
| Cache hints | Subscriptions | |
|---|---|---|
| Model | The client refetches after ttlMs | The server notifies the client of a change |
| Connection | None between requests | One stream held open per client |
| Fits | Serverless and fixed rosters | Long-running servers whose roster changes live |
| Staleness | Up to ttlMs | Until the notification arrives |
A held-open stream costs a connection for as long as the client stays, and on a platform with request duration limits it holds an invocation open. For a server with a fixed roster, cache hints do the job without it.
How do I limit or turn off subscriptions?
Set http.maxSubscriptions. It caps concurrent subscription streams per HTTP handler instance; 0 refuses them all:
A refused request gets JSON-RPC error -32603, Subscription limit reached, before any stream opens. Ordinary requests, tool calls, and progress notifications are unaffected. Omit the option to keep the MCP SDK's default.
The limit applies to each process or serverless instance on its own. It is not a deployment-wide quota, and it does not limit how long an accepted stream stays open.
Run the example
Use Node.js 22.12 or later and pnpm. From a checkout of the xmcp repository:
List the tools and look at the end of the result:
The example's README has the resource reads and the refused subscription.
Common questions
Do MCP clients cache tools/list by default?
Not from an xmcp server. The default hint is ttlMs: 0, so a client that follows the hints refetches each time. Set a ttlMs to allow reuse.
Do older clients get cache hints?
No. Clients on protocol revisions before 2026-07-28 do not receive ttlMs or cacheScope, so setting them does not change behavior for those clients.
Do cache hints replace listChanged notifications?
They complement them. A hint says how long a result may be reused; a notification says it changed now. A server can offer both, or cache hints alone.
Is this the same as HTTP caching?
No. These fields are part of the MCP result and are read by the MCP client. They are not Cache-Control headers, and MCP requests are POSTs.
Can a tool result be cached?
Cache hints apply to listings, resource reads, and server/discover. Tool calls are not in the list of cacheable results.
Next steps
- Cache hints reference for the config schema.
- Transports for subscription stream limits.
- MCP 2026-07-28: what changed for the rest of the revision.
