mcp-cache-kit

Correct, leak-safe caching for the new MCP cache semantics (SEP-2549).

The MCP spec 2026-07-28 release candidate adds SEP-2549: tools/list, resources/read (and the other list results) now carry ttlMs and cacheScope so clients, gateways, and proxies can cache them — modeled on HTTP Cache-Control. It is brand-new and has essentially no dedicated tooling. Generic caches store results "somehow" and ignore cacheScope, which is a real security trap: a result marked cacheScope: "private" that gets cached and served across users is a cross-user data leak.

mcp-cache-kit is the small, correct layer for exactly this:

- Server side — set the fields right (withCacheHints).
- Client / proxy side — a cache that honors ttlMs and never serves a private result across authorization contexts (McpResultCache).
- A guard — decide if any result may be cached for a given scope, with a clear reason (cacheSafety / assertCacheSafe).

Zero runtime dependencies. TypeScript strict, ESM + CJS, Node 20+. The @modelcontextprotocol/sdk is an optional peer — the helpers also work on plain result objects, so you can use it without the SDK.

> ⚠️ The 2026-07-28 spec is a release candidate. Field names and semantics may still shift before final. This library models them conservatively and is intentionally tolerant of missing/malformed fields (it treats anything it cannot prove safe as uncacheable).

What SEP-2549 actually says

Verified against the spec source (schema/draft/schema.ts and docs/.../utilities/caching.mdx):

Cacheable results extend a CacheableResult shape with two top-level fields:

| Field | Type | Meaning |
| ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------ |
| ttlMs | number (@minimum 0) | Freshness window, like Cache-Control: max-age. 0 = immediately stale. Absent/negative → treat as 0. |
| cacheScope | "public" \| "private" | Like Cache-Control: public vs private. See below. |

- "public" — the response has no user-specific data. Any client or intermediary MAY cache it and serve it across authorization contexts.
- "private" — the response MAY be cached and reused only within the same authorization context. Caches MUST NOT be shared across authorization contexts (a different access token / user / session needs a different cache entry).

Applies to tools/list, resources/list, resources/templates/list, prompts/list, and resources/read.

> The spec also warns: a "public" result from an authenticated endpoint can still be shared between callers, and you MUST NOT rely on cacheScope alone to prevent unauthorized access. This library enforces the scope boundary for you, but you still own labeling scopes honestly and authenticating at the origin. See SECURITY.md.

The cross-user-leak trap

              tools/list / resources/read
   user A  ───────────────────────────────►  proxy (caches by request only)
                                                   │ stores result, ignores cacheScope
   user B  ───────── same request ──────────►  proxy
                                                   │ returns A's cached result  ← LEAK

If the cached result was cacheScope: "private" (A's inbox, A's tenant config, …), user B just received another user's data. mcp-cache-kit keys every entry by the request and the caller's scope identity, so a private entry for A is structurally unreachable for B.

Install

```bash
npm install mcp-cache-kit