How Claude Code uses prompt caching changedprompt-caching
Nearest release: v2.1.283, published 5 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 26 Sep 2026 00:29 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 26 Sep 2026 00:37 UTC.
Upstream edited
Recorded here
Lines+29added
Lines−14removed
From line
60
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits35to this page, all time
### Connecting or removing an MCP server ### Connecting or disconnecting an MCP server
The whole hunk
from line 60, old and new numbered
/
from line 60
6060
6161## Actions that invalidate the cache
6262
63These actions cause the next request to miss part or all of the cache. You see a one-time slower, more expensive turn, after which the new prefix is cached. Most of them are avoidable mid-task once you know they have a cost. A model switch can feel free until you notice the slower turn that follows.
63These actions can cause the next request to miss part or all of the cache. You see a one-time slower, more expensive turn, after which the new prefix is cached. Most of them are avoidable mid-task once you know they have a cost. A model switch can feel free until you notice the slower turn that follows.
6464
6565* [Switching models](#switching-models)
6666* [Changing effort level](#changing-effort-level)
6767* [Turning on fast mode](#turning-on-fast-mode)
68* [Connecting or disconnecting an MCP server](#connecting-or-disconnecting-an-mcp-server)
68* [Connecting or removing an MCP server](#connecting-or-removing-an-mcp-server)
6969* [Enabling or disabling a plugin](#enabling-or-disabling-a-plugin)
7070* [Denying an entire tool](#denying-an-entire-tool)
7171* [Compacting the conversation](#compacting-the-conversation)
from line 102
102102
103103The cost applies once per conversation. After the first fast mode turn, Claude Code keeps sending the header and varies only the request's speed setting, which is not part of the cache key. Turning fast mode off, the [automatic fallback to standard speed](/docs/en/fast-mode#handle-rate-limits) after a rate limit, and turning it back on later all keep the cache. If you [run out of usage credits](/docs/en/fast-mode#handle-rate-limits) mid-session, Claude Code retries each rejected fast mode request at standard speed the same way, so this fallback also keeps the cache. `/clear` and `/compact` reset this, since they rebuild the cache at those points anyway.
104104
105### Connecting or disconnecting an MCP server
105### Connecting or removing an MCP server
106106
107107Tool definitions sit in the system prompt layer, so the cache invalidates when the set of tool definitions in the request changes between turns. Toggling the [advisor tool](/docs/en/advisor) is an exception: its definition sits after the cache breakpoint, so enabling or disabling `/advisor` keeps the cached prefix intact. Whether an [MCP server](/docs/en/mcp) change does this depends on whether its tools are deferred by [tool search](/docs/en/mcp#scale-with-mcp-tool-search) or loaded into the prefix:
108108
109109* **Deferred tools**, the default on supported models: a server connecting, disconnecting, or changing its tool list only appends new content and doesn't disturb anything already cached.
110* **Tools loaded into the prefix**: any change to them invalidates the cache. This happens when [tool search is unavailable or disabled](/docs/en/mcp#configure-tool-search), such as on Google Cloud's Agent Platform models earlier than the Claude 4.5 generation, with a custom `ANTHROPIC_BASE_URL` gateway, or on a Microsoft Foundry [deployment hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) once Claude Code detects that the deployment rejects tool search. It also happens for a server or tool marked [`alwaysLoad`](/docs/en/mcp#exempt-a-server-from-deferral), and for definitions kept upfront by [threshold-based loading](/docs/en/mcp#configure-tool-search).
110* **Tools loaded into the prefix**: adding a definition invalidates the cache, and so does removing one on purpose. This is the case when [tool search is unavailable or disabled](/docs/en/mcp#configure-tool-search), such as on Google Cloud's Agent Platform models earlier than the Claude 4.5 generation, with a custom `ANTHROPIC_BASE_URL` gateway, or on a Microsoft Foundry [deployment hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) once Claude Code detects that the deployment rejects tool search.
111111
112When tools load into the prefix, the most common cause of an invalidation is a server connecting or disconnecting mid-session, which can happen without any action on your part: a stdio server's process exits, an HTTP session expires, or a server [reconnects automatically after a transient failure](/docs/en/mcp#automatic-reconnection). A connected server can also push a [dynamic tool update](/docs/en/mcp#dynamic-tool-updates) that changes its tool list.
112Without tool search, whether a mid-session server change invalidates the cache depends on what changed. For each change, this table gives whether the cache is kept and what happens to the tool definitions in the next request.
113113
114| Mid-session change | Cache | Tool definitions in the next request |
115| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
116| A server connects, or a [dynamic tool update](/docs/en/mcp#dynamic-tool-updates) adds tools | Invalidated | The new definitions are added |
117| A server drops out with no action on your part, such as a stdio server's process exiting | Kept | The server's definitions stay unchanged. A call to one of its tools returns an error instead of running |
118| A remote server [reconnects automatically](/docs/en/mcp#automatic-reconnection) after its connection drops | Kept, unless a request sent while the server reconnects adds the `WaitForMcpServers` tool, which invalidates the cache once | The server's definitions stay unchanged. A request sent while the server reconnects can add `WaitForMcpServers` when the conversation hasn't listed it yet, and the tool then stays listed for the rest of the conversation |
119| You remove a tool on purpose, such as with a [deny rule](#denying-an-entire-tool) or by disabling its server in `/mcp` | Invalidated | The definition is removed |
120
121When you resume a conversation whose tools load into the prefix, one of its MCP servers can still be connecting as the first request goes out. If the transcript recorded that server's tool definitions, that request includes them as recorded, so it doesn't change when the server finishes connecting with the same tools.
122
114123Editing your MCP config does not by itself change the cache. The new config takes effect only after a restart, which is when the server connects or disconnects.
115124
116125### Enabling or disabling a plugin
from line 132
123132
124133#### Plugins that provide MCP servers
125134
126When you enable or disable a plugin that provides [MCP servers](/docs/en/plugins/components#mcp-servers), Claude Code follows the same rules as when you [connect or disconnect an MCP server](#connecting-or-disconnecting-an-mcp-server):
135When you enable or disable a plugin that provides [MCP servers](/docs/en/plugins/components#mcp-servers), Claude Code follows the same rules as when you [connect or remove an MCP server](#connecting-or-removing-an-mcp-server):
127136
128137* If Claude Code defers the server's tools, it keeps the cache.
129138* If Claude Code loads them into the prefix, the next request re-reads the entire conversation.
from line 341
332341
333342Disabling caching is occasionally useful when debugging caching behavior with a specific model or provider. To turn it off, set one of these environment variables to `1`:
334343
335| Variable | Effect |
336| ------------------------------- | ----------------------- |
337| `DISABLE_PROMPT_CACHING` | Disable for all models |
338| `DISABLE_PROMPT_CACHING_HAIKU` | Disable for Haiku only |
339| `DISABLE_PROMPT_CACHING_SONNET` | Disable for Sonnet only |
340| `DISABLE_PROMPT_CACHING_OPUS` | Disable for Opus only |
341| `DISABLE_PROMPT_CACHING_FABLE` | Disable for Fable only |
344| Variable | Effect |
345| ------------------------------- | ----------------------------------- |
346| `DISABLE_PROMPT_CACHING` | Disable for all models |
347| `DISABLE_PROMPT_CACHING_HAIKU` | Disable for the default Haiku model |
348| `DISABLE_PROMPT_CACHING_SONNET` | Disable for Sonnet only |
349| `DISABLE_PROMPT_CACHING_OPUS` | Disable for Opus only |
350| `DISABLE_PROMPT_CACHING_FABLE` | Disable for Fable only |
351
352`DISABLE_PROMPT_CACHING_HAIKU` applies to the default Haiku model, the model the `haiku` alias resolves to. It disables caching wherever that model runs, including the main conversation when it is your main model. Covering the main conversation requires Claude Code v2.1.283 or later.
353
354The variable also covers a background model you set with the deprecated `ANTHROPIC_SMALL_FAST_MODEL` variable, when that model differs from your main model.
355
356A different Haiku version that you pin as your main model keeps caching; set `DISABLE_PROMPT_CACHING` to disable caching for it.
342357
343358To set caching policy across an organization, put any of these or the [TTL variables](#cache-lifetime) in the `env` block of [managed settings](/docs/en/managed-settings). For normal use, leave caching enabled.
344359
No line in this hunk matches that.