Per-component cache hints for modern (2026-07-28) results.
Complete results of tools/list, prompts/list, resources/list,
resources/templates/list, resources/read and server/discover carry
ttlMs and cacheScope
(caching).
The defaults come from the application environment, validated when
:conduit_mcp starts:
config :conduit_mcp, cache_ttl_ms: 60_000, cache_scope: :private(cache_ttl_ms a non-negative integer, cache_scope :private or
:public.) A tool, prompt or resource can override them:
# DSL, inside a tool/prompt/resource block
tool "catalog", "Public catalog" do
cache ttl_ms: 5_000, scope: :public
handle fn _conn, _params -> text("...") end
end
# ConduitMcp.Component option
use ConduitMcp.Component, type: :tool, description: "...",
cache: [ttl_ms: 5_000, scope: :public]Either key may be omitted; it then falls back to the global default.
ConduitMcp.Endpoint collects its components' :cache options.
Resolution
- A list result: the minimum TTL across the listed items, and
privateif any listed item is private — or is gated by ascope(SV-9: a scoped item must never be cached as public, even when the global default is:public). An empty list uses the defaults. resources/read: the hint of the resource that serves the URI (its exact static URI, else the first matching template),privatewhen it is scoped.server/discover: the defaults.
Declaring both scope and cache scope: :public on one item is a
compile error.
Manual servers
A use ConduitMcp.Server, dsl: false module gets the defaults (with the
SV-9 rule applied through its __scope_for_*__/1 lookups, if any). It may
define __cache_hints__/0 returning a hints/0 to declare overrides.
Summary
Types
A declared override; nil keys fall back to the defaults.
The hints a server declares (__cache_hints__/0): tools and prompts by
name, resources as {uri_or_template, hint} in dispatch order.
Functions
The hints server_module declares (empty when it defines no
__cache_hints__/0).
The cache hints for method's complete result from server_module
(see "Resolution"), or nil for a method without them.
Validates the global :cache_ttl_ms / :cache_scope application env;
raises ArgumentError naming the key.
Types
@type hint() :: %{ttl_ms: non_neg_integer() | nil, scope: :private | :public | nil}
A declared override; nil keys fall back to the defaults.
@type hints() :: %{ tools: %{optional(String.t()) => hint()}, prompts: %{optional(String.t()) => hint()}, resources: [{String.t(), hint()}] }
The hints a server declares (__cache_hints__/0): tools and prompts by
name, resources as {uri_or_template, hint} in dispatch order.
Functions
The hints server_module declares (empty when it defines no
__cache_hints__/0).
@spec resolve(module(), String.t() | nil, map(), map()) :: ConduitMcp.Protocol.Modern.cache() | nil
The cache hints for method's complete result from server_module
(see "Resolution"), or nil for a method without them.
@spec validate_config!() :: :ok
Validates the global :cache_ttl_ms / :cache_scope application env;
raises ArgumentError naming the key.