When AI Agents Hammer tools/list: Building a Caching-Aware MCP Server (SEP-2549)

A developer built a caching-aware MCP server implementing SEP-2549, which adds ttlMs and cacheScope fields to cacheable discovery results like tools/list. Testing with GitHub Copilot CLI showed the client fired nine tools/list calls in roughly 40 seconds, illustrating how recursive agent planning loops can turn discovery endpoints into a self-inflicted database DoS risk. The server publishes cache hints both in the JSON-RPC result and as a Cache-Control header, while tools/call remains no-store.

Part 2 of 2. Part 1 https://dev.to/sindhuja sudhakar/why-mcp-dropped-the-handshake-building-a-bare-metal-stateless-client-sep-2575-277d covered statelessness; here I tackle caching. Part 1 was about statelessness, now shipped in the 2026-07-28 spec. This time it's another feature from that same spec: caching SEP-2549, "TTL for List Results" . It adds two tiny fields — ttlMs and cacheScope — to cacheable results, giving clients a way to avoid re-fetching the same discovery data. So I built a server that emits them, pointed real AI clients at it, and watched what actually happened. The result surprised me. AI agents plan in loops. A human calls a tool because they decided to; an agent can call — and re-discover — the same tools dozens of times inside a single planning loop. That changes the economics of the protocol: one user request fans out into many MCP calls. A ReAct-style agent can repeatedly re-check the available tools during a multi-step task, calling my discovery endpoint tools/list over and over. In a toy server that's harmless — the tool list is a constant. In a real one it isn't. Building a genuine tools/list means querying a service registry , filtering tools through RBAC , assembling input schemas from config, applying feature flags — one or more backend round-trips per call . Now multiply that by a recursive planning loop across many agents, and my discovery endpoint has quietly become a self-inflicted DoS risk for my own databases. php flowchart LR A "AI agent<br/ recursive planner " -- |tools/list x9| S MCP Server S -- |registry + RBAC + schema| DB Corporate DB style DB fill: f8d7da,stroke: 842029 This isn't hypothetical. When I pointed GitHub Copilot CLI at my server, it fired nine tools/list calls in ~40 seconds in one short session — plus repeated re-initializes. That's the storm SEP-2549 is meant to tame. ttlMs and cacheScope SEP-2549 lets the server advertise, right in the discovery result, how long the schema may be cached and by whom. The fields sit at the top level of the result a CacheableResult : // a tools/list result { "tools": / ... / , "ttlMs": 300000, "cacheScope": "private" } Cache-Control: max-age . Tool schemas rarely change, so a 5-minute window collapses a burst of planning turns into a single fetch. "public" "private" Cache-Control: public vs private . And a rule worth underlining: the spec marks read/discovery results cacheable — server/discover , tools/list , prompts/list , resources/list , resources/templates/list , even resources/read — but not actions. tools/call is always no-store . You cache "what can I do," never "do it." ⚠️ Schema note: In my server I group the hint under meta.cache for readability, but the spec puts ttlMs and cacheScope at the top level of the result the CacheableResult shape shown above , not under meta . The values and semantics are what matter for this walkthrough; check the caching spec for the exact field placement. My FastAPI server exposes three read-only repo tools get git diff , inspect file structure , fetch logs and publishes the hint in two places from one source of truth, so both smart clients and dumb proxies can act on it: TOOLS TTL MS = int os.getenv "MCP TOOLS TTL MS", str 5 60 1000 TOOLS CACHE SCOPE = os.getenv "MCP TOOLS CACHE SCOPE", "private" def cache meta : return {"ttlMs": TOOLS TTL MS, "cacheScope": TOOLS CACHE SCOPE} def cache control header ttl ms=TOOLS TTL MS, scope=TOOLS CACHE SCOPE : visibility = "public" if scope == "public" else "private" return f"{visibility}, max-age={ttl ms // 1000}" meta.cache rides inside the JSON-RPC result — for MCP-aware clients/proxies. Cache-Control maps the same values to an HTTP header — for gateways that only read headers. But here's the layer that actually saved my database. Because I can't trust the caller to honor ttlMs more on that in a second , the server caches its own expensive discovery build, keyed by cacheScope : python class DiscoveryCache: def get self, client id, build : key = " " if self.scope == "public" else f"client:{client id}" now = time.monotonic with self. lock: entry = self. entries.get key if entry and now < entry 0 : self.cache hits += 1 return entry 1 , True served from memory, no DB hit self.backend builds += 1 pay the backend cost ONCE value = build self. entries key = now + self.ttl s, value return value, False Wired into tools/list , the expensive build tool list my stand-in for the registry + RBAC + schema queries now runs at most once per TTL window, no matter how often the client re-discovers . Worth being precise: SEP-2549 gives the consumer a caching hint ; this DiscoveryCache is a separate server-side defense I control regardless of whether any consumer honors that hint. They share the same ttlMs value but do different jobs. Two caveats I'd flag in a real build. First, I key the private scope by client id , but the spec's private semantics are per authorization context — so client id is really a stand-in for "the auth principal and scopes that decide who may share a response." Second, keeping the cache in-process no shared Redis preserves Part 1's statelessness, but it doesn't give me globally shared cache state — it trades cross-instance sharing for duplication: a burst spread across four replicas can trigger up to four backend builds instead of one. No Redis lock — but not free either. php flowchart LR A "AI agent<br/ tools/list x9" -- S MCP Server S -- |1st call only| DB Corporate DB S -.- |calls 2-9: served from memory| A style DB fill: f8d7da,stroke: 842029 Hypothesis: if the server refuses to rebuild the tool list more than once per TTL window, an agent's repeated tools/list calls should collapse to a single backend hit — regardless of whether the client caches anything . This is where it got interesting. Finding 1 — the server-side cache works. Replaying the nine-call storm collapses it to a single backend build: Replaying a 9-call discovery storm from one client... tools/list 1: servedFromServerCache=False tools/list 2..9: servedFromServerCache=True discovery cache stats: {'backendBuilds': 1, 'cacheHits': 8} = 9 client discovery requests collapsed to 1 backend build s 88% avoided I confirmed it end-to-end with real Copilot CLI: it re-requested tools/list repeatedly, yet my server log showed fromCache: true and backendBuilds pinned at 1 8 of 9 builds avoided, 88.9% . The DB was queried once and shielded after that. Finding 2 — the clients I tested didn't honor ttlMs . My server advertised ttlMs: 300000 , but both Copilot CLI and Cursor re-requested tools/list repeatedly and didn't cache it client-side. Their handshakes differ — Copilot CLI is dual-era, probing server/discover before falling back to initialize ; Cursor took the legacy initialize path — but neither honored the cache hint in my runs. I'll be careful with this one: it doesn't mean MCP clients ignore ttlMs in general — SEP-2549 is final in the 2026-07-28 spec, and client support is still landing. The two I tested just hadn't wired it up yet, which is exactly why the server can't rely on the hint being honored. Finding 3 — client-side caching is timing-sensitive. I wrote a simulated edge proxy that does honor ttlMs ; normally it collapses 20 planning turns to ~2 fetches. But in a deliberately adversarial timing setup — a slower laptop where each round-trip took ~2 seconds, matching the proxy's own 2-second window — the client cache expired just before every next call, giving 0% avoided . The same run showed the server-side cache still serving 19 of 20 calls from memory. TTL effectiveness depends on the relationship between cache TTL, request frequency, and round-trip latency — so client-side caching is dependent on consumer behavior and timing, while server-side caching stays effective even when the client ignores the hint. Worth stating plainly: this protects the server's backend, not the client's. The agent is the source of the load; the corporate database behind my server is the victim. And there are three places a cache can step in — each reduces the load reaching the DB, and the further upstream it lives, the more work it eliminates: php flowchart LR A Agent -- |1. client cache| P Edge Proxy P -- |2. Cache-Control| S MCP Server S -- |3. server-side cache| DB Corporate DB style DB fill: f8d7da,stroke: 842029 | Layer | Mechanism | Protects | |---|---|---| | Client | honors ttlMs / cacheScope | DB + network + server CPU | | Gateway / proxy | Cache-Control / protocol-aware caching | DB + server CPU | | Server | local discovery cache | DB | Since I can't count on the clients I tested to honor the hint, the server-side cache is the only layer I fully control — and therefore the only protection I can enforce unilaterally today. So my server does both jobs at once: it advertises ttlMs / cacheScope for the ecosystem that's catching up, and it enforces the same ttlMs internally for right now. 💡 Key takeaway: A cache hint is only advice — it protects nothing until a consumer acts on it. Advertise ttlMs / cacheScope for the ecosystem you wish you had, and enforce the same TTL inside the server for the ecosystem you actually have. I assumed the hard part would be designing the cache hint. It wasn't — that's two fields. The surprise was that advertising it changed nothing in the clients I tested : both kept requesting tools/list despite the ttlMs I returned. The protection had to come from the one place I fully control — the server enforcing its own advertised TTL. The lesson mirrors Part 1: a protocol capability can ship before every client has adopted it, so a server that wants the benefit today has to implement both sides of the contract itself. tools/list into a self-inflicted DoS — every planning turn re-runs the registry/RBAC/schema queries behind discovery. public vs Tying both parts together: Statelessness removes protocol-level affinity without any client cooperation. Caching has two sides — the server can advertise a policy and defend its own backend alone, but the biggest savings only arrive when clients and proxies honor the hint too.