Claude Code Prompt Caching: What Gets Cached and Why for CCA-F

Claude Code prompt caching automatically stores your system prompt, conversation history, and tool results in a server-side cache with a 5-minute TTL — reducing input token costs by up to 90% on repeated content. Understanding what Claude Code caches by default, and when the cache resets, is essential for the CCA-F exam.

What Is Prompt Caching in Claude Code?

Prompt caching is a server-side mechanism in the Claude API that stores a snapshot of the rendered token prefix up to a designated breakpoint. Claude Code, the agentic CLI product built on the Messages API, applies this mechanism automatically to manage costs across long agentic sessions. When Claude Code sends a request to Anthropic's servers, the input is rendered in a fixed order: tool definitions first, then the system prompt, then the conversation messages. Content marked with a cache_control breakpoint is stored on Anthropic's servers and reused by subsequent requests that send the same bytes in the same order.

The practical effect is that stable, repeated content — a long system prompt, a growing conversation history — does not need to be retokenized and processed on every API call. For candidates preparing for the Anthropic Claude Code certification, formally the Claude Certified Architect — Foundations (CCA-F) exam, this mechanism is central to understanding how agentic architectures manage cost and latency at scale.

The minimum cacheable prefix is 4,096 tokens on Opus 4.8, Opus 4.7, Opus 4.6, and Haiku 4.5, and 2,048 tokens on Sonnet 4.6. Prompts shorter than those thresholds skip caching silently — no error is raised, and cache_creation_input_tokens in the response simply stays at zero.

What Does Claude Code Cache Automatically?

Claude Code applies prompt caching to three layers of its agentic context:

• The system prompt. Claude Code sends a stable system prompt on every turn that defines the agent's capabilities, tools, and operating context. Because this content does not change within a session, it is the ideal cache candidate. A breakpoint on the final system block stores both the tool definitions and the system prompt together, since tool definitions render before the system prompt in the API's fixed render order.
• The conversation prefix. As the agentic loop runs, prior turns accumulate into the conversation history. Each time Claude Code sends a new request, the history up to the current turn becomes the stable prefix. Placing a cache breakpoint at the end of the previous turn's last message avoids reprocessing the entire prior context on every new step.
• Prior tool call-and-result pairs. Tool calls and their results from earlier turns are part of the growing conversation prefix. Once a cache breakpoint has been set beyond a completed tool result, that content is served from cache on the next turn rather than retokenized from scratch.

What is not cached is the current turn's dynamic content: the new user message, new tool calls being processed right now, timestamps, or volatile data injected per request. Those always sit after the last breakpoint and are processed at full cost. Any byte change anywhere in the cached prefix invalidates everything after it — this is the single invariant everything else follows from.

How Does the 5-Minute Cache TTL Affect Agentic Loops?

The default cache TTL is five minutes. A one-hour TTL is also available at a higher write cost. In a busy Claude Code session running continuous agentic loops, the five-minute TTL rarely causes problems — each request arrives well within the window and the cache entry stays warm.

The TTL becomes a cost problem when the agentic loop pauses. Consider a Claude Code agent that checks a repository every eight minutes. The five-minute TTL expires between runs. When the agent fires again, the system prompt must be re-cached, paying the 1.25× write premium instead of the ~0.1× read cost. Over many runs, this negates most of the caching benefit.

The CCA-F exam tests this architectural pattern. The key insight: the five-minute TTL counts from when the cache entry was written, not from each request. Pausing longer than the TTL means the next run starts cold. The three architectural solutions are:

1. Schedule agentic runs within the TTL window so the cache stays warm between invocations.
2. Switch to the one-hour TTL for workflows with longer gaps between runs.
3. Pre-warm the cache by sending a brief request just before a scheduled run, so the main run reads from a warm entry.

What Are the Cost Savings for Long-Context Claude Code Workflows?

Cache reads are billed at approximately one-tenth of the standard input token rate. Cache writes carry a 1.25× premium on the default five-minute TTL, or a 2× premium for the one-hour TTL. Two reads break even on the five-minute TTL; three reads break even on the one-hour TTL. Every additional read beyond those thresholds reduces cost.

For a Claude Code session with a 10,000-token stable context — tool definitions and a detailed system prompt — each uncached turn costs 10,000 input tokens for that prefix alone. After the first cache write, subsequent turns cost roughly 1,000 tokens for the same prefix. Over a 20-turn session, the savings on the stable prefix approach 90%.

As of publication, Claude Sonnet 4.6 input pricing is $3.00 per million tokens (verify at the Anthropic pricing page — rates change). Cache reads on the same content cost approximately $0.30 per million tokens. For long-context workflows that make dozens of requests per session — a realistic pattern in agentic Claude Code runs querying tools repeatedly — the savings compound quickly.

How Do MCP Tool Definitions Affect the Prompt Cache?

Architectures that use Model Context Protocol (MCP) — for example, a Claude Code agent connected to a GitHub MCP server or a custom MCP server exposing internal APIs — provide some of the clearest model context protocol examples of how tool definition order affects prompt caching behavior. The cache interacts with the MCP tool layer in two distinct ways.

MCP tool definitions are part of the tools array, which renders at position zero in the API's fixed order. They are included in the cached prefix. Any change to the MCP tool definitions — adding a server, removing a tool, or changing the order — invalidates the entire cache from that point forward, including the system prompt and all conversation history downstream. For the CCA-F exam: keep MCP tool declarations in a stable, deterministic order across turns.

A common silent invalidator is assembling the tools list from a set or dictionary that does not preserve insertion order — each run may serialize server names differently, producing a different byte sequence even when the connected servers are unchanged. The fix is explicit sorting before building the request:

• Non-deterministic (cache miss risk): tools = [servers[n].definition for n in connected_mcps]
• Deterministic (stable cache hits): tools = [servers[n].definition for n in sorted(connected_mcps)]

MCP tool results accumulate in the conversation messages array. Once a tool result from a prior turn is part of the conversation prefix and a cache breakpoint sits beyond it, that result is served from cache on the next turn. This is the same prefix-match behavior that governs all cached content: stable content before the breakpoint is reused; volatile new tool results after it are processed at full cost.

What Does the CCA-F Exam Test About Prompt Caching in Agentic Systems?

The Claude Certified Architect — Foundations (CCA-F) exam tests prompt caching at the level of architectural reasoning, not just API parameter syntax. Candidates should be prepared to apply the following concepts:

• Prefix match semantics. Caching is an exact byte match. Any change at any position in the prefix invalidates everything after it — not just the changed block.
• Render order. The rendered input order is always tools → system → messages. A change to tool definitions invalidates the system cache and message cache downstream.
• Silent invalidators. Inserting datetime.now() in the system prompt, using non-deterministic JSON serialization, or varying the tool set between turns all silently break the cache. No error is raised; cache_read_input_tokens in the response simply stays at zero.
• TTL implications for scheduled agents. Agentic loops that pause longer than the active TTL lose the cache on the next run and pay the write premium again.
• Cache hit verification. Confirm caching is working by checking usage.cache_read_input_tokens and usage.cache_creation_input_tokens in the API response.

Plinth-Authored Practice Scenario

A developer builds a Claude Code agent connected to three MCP servers. The agent runs on a ten-minute schedule. The system prompt is 12,000 tokens and includes the MCP tool definitions. Despite prompt caching being configured, costs are not dropping as expected. Which two changes are most likely to fix the problem?

Model answer: First, the ten-minute run interval exceeds the default five-minute TTL. Each run is writing a fresh cache entry rather than reading the existing one. Switching to the one-hour TTL — or scheduling runs within five minutes of each other — would let the cache warm across runs. Second, verify that the MCP tool definitions are declared in a stable, deterministic order on every run. If they are assembled from a data structure that does not preserve insertion order, each run may serialize the tool list differently. This produces a byte-level mismatch that causes a cache miss even when the semantic content is unchanged. Both issues result in cache_creation_input_tokens appearing in every run's usage object instead of cache_read_input_tokens.