How do I cache MCP tool results safely?

What should I check, step by step?

1. Decide per tool, from your own allowlist: cache read-only lookups (search, fetch, get); never cache tools that send, write, pay, delete or deploy.

2. Treat annotations as input to that decision only for servers you trust. readOnlyHint defaults to false and destructiveHint to true, so a tool with no annotations should be treated as one that changes things.
3. Build the key from: server URL, serverInfo.version, tool name, a hash of the tool's definition (description, inputSchema and outputSchema), the canonicalized arguments, and the caller's identity or tenant.
4. Canonicalize arguments before hashing: RFC 8785 (JCS) sorts object keys recursively, keeps array order and serializes numbers one way, so {"a":1,"b":2} and {"b":2,"a":1} produce the same key. JCS does not normalize Unicode, so normalize strings yourself first if your inputs need it.
5. Never cache results with isError: true; those are execution errors meant for the model to read and retry.
6. Set a short TTL that matches how fast the underlying data changes. Tools that reach an open world (web search, live prices, inboxes) go stale fastest.
7. Invalidate on notifications/tools/list_changed, on a new serverInfo.version, and when the tool definition hash changes.
8. Keep the cache per user or per credential scope, so one person's results are never served to another.
9. Mark cached results as cached (with their age) in what you hand the model or the user, so a stale answer can be recognized.

What the MCP specification gives you to work with

In the 2025-11-25 schema, ToolAnnotations are all hints: readOnlyHint (the tool does not modify its environment, default false), destructiveHint (default true), idempotentHint (calling repeatedly with the same arguments has no additional effect on its environment, default false) and openWorldHint (default true). The schema says they are not guaranteed to describe tool behavior faithfully.

• idempotentHint is about side effects, not about getting the same answer back. A read-only tool can return a different result a minute later; an idempotent write is still a write. Neither one makes a result safe to reuse indefinitely.
• A server that declares tools.listChanged SHOULD send notifications/tools/list_changed when its tools change, and the initialize result carries serverInfo with a required version string. Both are natural cache-invalidation signals.
• Tool execution errors come back in the result with isError: true, so the client can tell an error result from a successful one before storing it.

Why caching a side-effecting tool is dangerous

If a send_email or create_invoice call is answered from cache, the model sees a success message while nothing was sent or created. Retrying the same request is how agents recover from errors, so a cache in front of a write tool quietly turns retries into no-ops.

• Results also carry the caller's permissions. A cache keyed only on tool and arguments can hand one user's private search results or file contents to another user who sends the same arguments.