Wiring MCP Tools Without Breaking Your Prompt Cache

Tools are where most agents earn their keep — and where most prompt caches quietly die. The instant you connect an MCP server, you inject a block of tool schemas high in the prompt, exactly in the cache-sensitive region. Get the wiring wrong and every tool call rewrites your cache; get the auth, error handling, or idempotency wrong and the model either loops, repeats side effects, or stalls. This post is about wiring tools and MCP servers into a Claude agent so they're correct and cache-friendly, because in an agentic system those two goals are deeply intertwined.

MCP and the tool schema, briefly

Model Context Protocol is an open standard that connects Claude to external tools and data through MCP servers, which advertise a set of tools — each with a name, a description, and a JSON schema for its inputs. When a server connects, those tool definitions get serialized into the prompt so the model knows what it can call. That serialized block is large, stable within a session, and lives near the top of the prompt — which makes it prime cache real estate and, if mishandled, a prime cache hazard.

The first rule of wiring follows directly: serialize tool schemas deterministically. Sort tools by name, sort the keys inside each schema, and use one canonical serializer. If your MCP client returns tools in hash-map order that shifts run to run, the schema block's bytes change between sessions and sometimes between turns, and your cache misses for reasons that look like dark magic until you diff the bytes.

Auth that doesn't leak into the cached prefix

Authentication is the second trap. Tokens, session IDs, and per-request credentials must never end up serialized into the tool-definition block or the system prompt. They belong in the transport layer — request headers, a server-side handshake — not in the cacheable prompt text. Beyond the obvious security reason, a credential baked into the prefix is usually unique per session or rotates over time, so it acts as a cache-busting random value sitting exactly where you most want stability.

The clean pattern is a hard separation: the MCP server handles auth out of band when it connects, and what flows into the prompt is only the tool's public contract — names, descriptions, input schemas. Nothing secret, nothing per-request, nothing that changes between otherwise-identical turns.

flowchart TD
  A["MCP server connects (auth out of band)"] --> B["Tools sorted & canonically serialized"]
  B --> C["Schema block placed in cacheable prefix"]
  C --> D["Claude emits tool call with input"]
  D --> E{"Idempotency key seen before?"}
  E -->|Yes| F["Return stored result, skip side effect"]
  E -->|No| G["Execute & record result"]
  F --> H{"Error?"}
  G --> H
  H -->|Yes| I["Append structured error < retryable? >"]
  H -->|No| J["Append stable result to transcript"]

Error handling the model can actually use

When a tool fails, what you append to the transcript is a prompt the model will read and react to. Vague failures produce bad agent behavior — a terse "error" invites the model to retry blindly, while a raw stack trace wastes tokens and confuses it. The pattern is structured, actionable error results: a clear status, a short human-readable reason, and a signal about whether the failure is retryable. "Rate limited, retry after a moment" leads to patient retry; "Invalid argument: account_id must be numeric" leads to a corrected call; "Permission denied" leads the model to stop and ask rather than hammer the endpoint.

Keep these error payloads deterministic where you can. An error that embeds a fresh timestamp or trace ID becomes a poisoned block in the prefix once the conversation moves past it. If you must include a correlation ID for debugging, keep it out of the model-facing portion or accept that it sits in the volatile tail. The model needs the shape of the failure, not your observability metadata.

Idempotency so retries don't double-fire

Agents retry. They retry because a tool returned a retryable error, because the model second-guessed itself, or because a turn got replayed after a transient failure. If your tools have side effects — booking, charging, sending — naive retries cause duplicates. Idempotency is the defense: assign each side-effecting operation a stable idempotency key derived from its meaningful inputs, and have the server deduplicate on that key so a repeated call returns the original result instead of performing the action twice.

This pairs neatly with caching. A deterministic idempotency key means a repeated logical operation yields a repeated, stable result — which is exactly the content-addressable output the cache wants. Nondeterministic side effects and nondeterministic outputs are the same problem wearing two hats: both break either correctness or cacheability, and the fix for both is determinism keyed on the actual inputs.

Keeping the schema block stable across a session

One more wiring concern: tool sets sometimes change mid-session as servers connect or disconnect. Because the schema block sits high in the prompt, any change there invalidates the cache for everything below it. You can't always avoid that — connecting a new server genuinely changes what the model can do — but you can contain it. Place a cache breakpoint right after the tool block so the system prompt above it stays warm even when tools change. And avoid gratuitous churn: don't reorder tools, don't toggle servers on and off speculatively, and don't regenerate the schema serialization with different formatting between turns. Treat the tool block as stable infrastructure that changes only on real connect/disconnect events.

Done well, the result is an agent whose tools are secure, robust under failure, safe under retry, and gentle on the cache. The unifying idea is that everything the model reads — schemas, results, errors — is a prompt, and prompts that are deterministic and well-structured are both better behaved and cheaper to run.

Frequently asked questions

Why does connecting an MCP server sometimes spike my costs?

Because the new server's tool schemas are injected high in the prompt, invalidating the cache for everything below them and forcing a rewrite. Place a breakpoint right after the tool block to protect the system prompt above, and avoid connecting servers more often than necessary.

Where should auth tokens live?

In the transport layer — headers and the MCP handshake — never serialized into the prompt. Credentials in the prompt are both a security risk and a cache-buster, since they're typically unique per session and sit exactly in the stable region you want to reuse.

What makes a good tool error for an agent?

A structured result with a clear status, a short reason, and a retryable signal. That lets the model retry transient failures, correct invalid arguments, and stop on permission errors instead of looping. Keep observability IDs out of the model-facing payload.

How does idempotency relate to caching?

Both want determinism. An idempotency key derived from meaningful inputs makes a repeated operation return a stable result, which prevents duplicate side effects and keeps tool outputs content-addressable so they cache cleanly as the conversation moves on.

Bringing agentic AI to your phone lines

Wiring tools safely matters even more in real time, where an agent books appointments and charges cards live on a call. CallSphere's voice and chat agents call tools mid-conversation with auth, error handling, and idempotency built in. See the approach at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.