[FEATURE] Honor MCP tool result _meta.cache_hint to control prompt caching

Resolved 💬 2 comments Opened Mar 14, 2026 by clouatre Closed Apr 12, 2026

Problem Statement

Claude Code applies prompt caching to MCP tool results. In non-interactive workflows (subagents, benchmarks, one-shot pipelines), the cache is written once and never read, a net cost with zero benefit. There is currently no way for an MCP server to signal that its results should not be cached.

Proposed Solution

The MCP spec defines _meta on CallToolResult as client-only metadata not passed to the model. We propose that Claude Code treat _meta: { "cache_hint": "no-cache" } as an instruction to skip caching for that specific tool result. This gives servers per-result control without requiring a global session-level setting.

Alternative Solutions

DISABLE_PROMPT_CACHING=1 disables caching globally. A per-result hint is preferable because it lets read-only deterministic servers opt out while leaving caching intact for other tools in the same session.

Use Case Example

  1. A subagent is spawned for a single-pass code analysis task
  2. Claude Code calls analyze_file 10 times, each result gets cached
  3. The session ends; the cache is never read again
  4. With cache_hint: "no-cache", those writes are skipped, reducing unnecessary token costs

Additional Context

Reference implementation: https://github.com/clouatre-labs/code-analyze-mcp -- all CallToolResults carry _meta: { "cache_hint": "no-cache" } (issues #263, #269).

Category: MCP server integration
Priority: Medium - Would be very helpful

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗