Skip to main content

​
fastmcp.server.caching

Server-level cache hints for FastMCP (SEP-2549). A FastMCP server opts every SDK-cacheable result it emits into client-side caching by setting cache_ttl (seconds) and, optionally, cache_scope on the FastMCP constructor. The hint is uniform by construction: one server-level value applies to tools/list, prompts/list, resources/list, resources/templates/list, resources/read, and server/discover alike — no per-component surface and no aggregation. FastMCP does not hand-set the wire fields. It passes the hint through to the SDK low-level Server(cache_hints=...), whose runner fills ttlMs/cacheScope on every cacheable result via apply_cache_hint, leaving any field a handler set explicitly untouched. Honoring is modern-only and opt-in on the client: a hinted server is inert unless the client passes cache= and negotiates 2026-07-28.

​
Functions

​
build_cache_hints

Build the per-method CacheHint map for the SDK low-level server. cache_ttl is in seconds and is converted to the wire’s milliseconds. When cache_ttl is None the server emits no hint, so its wire output is identical to a server that never set one; a cache_scope given without a cache_ttl is meaningless (the client gates caching on the presence of a TTL) and is rejected rather than silently ignored. Returns None when no hint is set, or a map applying the same hint to every SDK-cacheable method otherwise. Raises:
  • ValueError: If cache_ttl is not positive, or if cache_scope is set without cache_ttl.