Skip to content

Cache Hints

Tell MCP clients how long they can reuse tool, prompt, and resource listings and resource contents.

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

MCP protocol revision 2026-07-28 adds cache hints to cacheable results: tools/list, prompts/list, resources/list, resources/templates/list, resources/read, and server/discover. Each result carries a ttlMs (how many milliseconds a client may reuse it) and a cacheScope ("private" to one caller, or "public" to any caller of the same server).

By default, every result is sent with ttlMs: 0 and cacheScope: "private", so clients refetch each time. Use the optional cacheHints field in xmcp.config.ts to let clients reuse stable results. Update both xmcp and @xmcp-dev/compiler to use this option.

xmcp.config.ts

Each key is a cacheable method. Each hint accepts:

FieldTypeDefault
ttlMsNon-negative integer0
cacheScope"private" | "public""private"

Unknown methods and fields fail the build. Clients on earlier protocol revisions do not receive cache hints, so this option does not change their behavior. A ttlMs or cacheScope returned directly by a handler or middleware takes precedence over configured hints.

Choosing a scope

Keep the default "private" scope unless a result is identical for every caller. Results vary between callers when an authorize policy or other auth-dependent middleware filters components, or when resource contents depend on the caller. Mark only those results that are truly shared as "public".

Per-resource hints

A resource can set cacheHint in its metadata. It applies to resources/read for that resource and overrides cacheHints["resources/read"] field by field:

src/resources/(config)/app.ts

The HTTP transport example configures listing cache hints and a per-resource hint.

One framework to rule them all