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.
Each key is a cacheable method. Each hint accepts:
| Field | Type | Default |
|---|---|---|
ttlMs | Non-negative integer | 0 |
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:
The HTTP transport example configures listing cache hints and a per-resource hint.
