Cache and freshness policy

The MCP server should avoid broad response caching until result contracts consistently carry source/freshness metadata. Incorrectly cached blockchain data can mislead AI summaries and users.

Current cache

The only intentional application cache is the BLURT price helper cache. It is narrow and short-lived:

• external price feed only;
• approximately 60 seconds;
• best-effort;
• failures do not invalidate on-chain data;
• USD/BTC values may be null when unavailable.

No generic response cache yet

Do not add a generic cache layer for account, wallet, history, witness, vote, post, community or pending reward tools in Phase 4. These values have different freshness expectations and source layers:

• Layer 1 account/wallet/reward/vote/witness state changes with blocks and account activity;
• Nexus/Bridge ranked posts and community views have their own indexing freshness;
• external market prices have separate freshness and failure modes;
• mixed dashboard-style tools combine several sources.

Requirement before broader caching

Before introducing per-tool TTLs, structured results should expose provenance/freshness metadata such as:

• source layer (layer1, nexus, external, mixed);
• retrieval timestamp;
• head block or index/version when available;
• cache hit/miss or freshness age;
• caveats for best-effort external data.

Until then, prefer correctness and transparent latency over silent stale responses.

Deployment-level caching

Reverse proxies and CDNs should not cache /mcp responses by default. MCP requests are JSON-RPC POSTs whose results depend on tool arguments and upstream state. If an operator experiments with caching, it should be explicit, endpoint-specific, and validated against stale-data risk.