[FEATURE] Honor MCP tool result _meta.cache_hint to control prompt caching
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
- A subagent is spawned for a single-pass code analysis task
- Claude Code calls
analyze_file10 times, each result gets cached - The session ends; the cache is never read again
- 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
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗