Skip to content
Back to blog

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:

FieldTypeMeaning
ttlMsNon-negative integerHow 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:

xmcp.config.ts

A tools/list result from this server now ends with:

JSON

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:

src/resources/(docs)/pricing.ts

A resource with no hint keeps the default. In the example, status://now returns the current time and is never reused:

ResultttlMscacheScopeSet by
server/discover3600000publiccacheHints in the config
tools/list, resources/list300000publiccacheHints in the config
resources/read docs://pricing86400000publicThe resource's cacheHint
resources/read status://now0privateDefault

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 authorize policy 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:

ResultChanges whenReasonable hint
Listings on a server with a fixed rosterYou deployMinutes
A resource updated on a scheduleThe schedule runsUp to the schedule interval
A resource with live dataConstantly0, 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 hintsSubscriptions
ModelThe client refetches after ttlMsThe server notifies the client of a change
ConnectionNone between requestsOne stream held open per client
FitsServerless and fixed rostersLong-running servers whose roster changes live
StalenessUp to ttlMsUntil 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:

xmcp.config.ts

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:

Shell

List the tools and look at the end of the result:

Shell

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

One framework to rule them all