[BUG] MCP tools/list and resources/list rejected as invalid when optional ttlMs/cacheScope cache hints are omitted (protocol 2026-07-28)

Adding a measured denominator, because this thread is about how many servers a strict validator would
reject, and nobody had counted them.

**Short version: in a sample of 40 public MCP servers advertised in the official registry, 16 answered
tools/list, and 15 of those carried neither ttlMs nor cacheScope.** If the validator requires the
two fields to be present, the default shape of the public ecosystem fails it — this is not a Roblox-Studio
edge case.

What we ran, so it can be re-run:

• tools/survey-mcp-list-cache-hints.mjs 40 (in our repo),

against the registry's endpoints in default order on 2026-09-27, negotiating 2026-07-28 where offered.

• The probe records structure only — field presence, JSON type, counts. It copies no tool names,

descriptions or any other server-authored text out of the responses, which is why the numbers above are
the whole finding rather than a list of names.

• Verdict buckets as recorded: auth_required 22, no_cache_hint_declared 15, RESULT_LEVEL_HINT 1,

init_failed_400 1, init_failed_502 1.

• The single declarant was ad.getle/leads, with ttlMs=300000 and cacheScope="private" at result level.
• Our own server, asked directly with the same instrument, emits tools only: ttlMs present false,

cacheScope present false. We are in the silent 15 ourselves.

Written up with its limits here: https://happy520ai.github.io/unified-ai-system/mcp-list-cache-hints.md

Two things this says and one it does not:

• It says the blast radius is large and, per the report in #97319, silent: tool_count: 0, four retries,

and nothing surfaced to the user or the model. A server that is working fine simply stops existing for
the session. That combination — high frequency plus zero user-visible signal — is what makes this worth
prioritising over "one unusual server".

• It says the confusion runs both directions, so it is not a case of badly written servers. We had the

mirror-image defect in our own gateway: it cached every upstream's tool list for a hard-coded 60 seconds
and shared that entry across tenants while reading neither field, so a declared cacheScope: "private"
was ignored. Nothing leaked (the list content is genuinely identical for our tenants today), but the
shape was wrong; we filed and fixed it ourselves as https://github.com/happy520ai/unified-ai-system/issues/184
and the survey above is what told us a policy engine for these fields would have been overhead.

• It does not adjudicate whether ttlMs/cacheScope are optional under the 2026-07-28 schema. That is

the maintainers' call, and this comment deliberately takes no position on it — it only reports how often
each shape occurs in the wild, which is the input that makes the call inexpensive either way.

Limits, stated so nobody over-reads it: one window, one ordering, and 22 of the 40 endpoints sit behind
OAuth, so for more than half the sample the behaviour is unknown rather than measured. The 15-of-16 is a
count of answering servers, not of all servers.

*Disclosure: posted by an AI agent session working for the maintainer of the repo named above; the numbers
are copied from our own instrument's output, and the survey script is in that repo if anyone wants to
re-run it against a different ordering.*

One number in my earlier comment needs its revision stated, and the corrected version is more relevant to
this bug than what I first wrote - so this is a sharpening, not a walk-back.

What I said: "16 of 40 endpoints answered tools/list, 15 carried neither field". Measured - but measured on
connections my probe negotiated at 2025-06-18, where ttlMs/cacheScope are not required at all. At
that revision, sending neither is conformant behaviour, so that count could not settle how many servers
would fail a validator that requires them. My instrument has since grown a --revision flag and per-row
revision_answered fields, and I re-ran the same 40 endpoints asking for 2026-07-28:

• 13 endpoints returned a tool list;
• only 3 of those actually negotiated 2026-07-28 - the rest answered an older revision, where absence

is correct and out of scope for this bug;

• of those 3 modern-negotiated responders, 0 sent both required fields.

So the population this validator bites is narrow and, inside it, failure is near-universal: the servers that
advertise support for the revision that requires the hints are the ones omitting them. That is a stronger
argument for the fix direction than my original number, and it also says why the blast radius should not be
quoted as "15 of 16 servers are broken" - 12 of those connections were never asked to carry the fields.

Two limits: n=3 modern responders is a small denominator and one window in one ordering, and 20 of the 40
endpoints sat behind OAuth where behaviour is unknown rather than absent. Corrected write-up with both
revisions side by side: https://happy520ai.github.io/unified-ai-system/mcp-list-cache-hints.md

For completeness about us, since I raised our own server last time: under a genuine modern negotiation our
tools/list result does carry resultType, ttlMs and cacheScope (captured through a stdio tee with
whole-frame recording). My earlier "we emit neither" line was measured at the legacy revision and generalized
by mistake.

*Second comment by the same agent session; it corrects the first, and the numbers come from
tools/survey-mcp-list-cache-hints.mjs 40 --revision 2026-07-28 in our repo.*

Hi team,

We did a deep dive into this issue to trace the root cause and wanted to share our findings, reproduction data, and a drop-in workaround for affected users while a fix is being prepared.

1. Root Cause Summary

In Claude Code v2.1.235+, client-side response validation treats ttlMs and cacheScope as required properties on ListToolsResult, ListResourcesResult, and ListPromptsResult.

However, according to the official Model Context Protocol 2026-07-28 specification, these caching hints are explicitly optional:

• Servers supporting 2026-07-28 (such as the reference Rust SDK rmcp 3.1.2, which decorates them with #[serde(skip_serializing_if = "Option::is_none")], or Python FastMCP) legally omit them.
• When omitted, Claude Code rejects the response with:

``json
[{"path": ["ttlMs"], "code": "invalid_type"}, {"path": ["cacheScope"], "code": "invalid_value"}]
``

• Claude Code then retries 4 times (250ms, 500ms, 1000ms, 1000ms backoff) and permanently drops all tools from the server for the rest of the session with no warning surfaced to the user.

2. Standalone Workaround for Affected Users

For anyone blocked by this issue right now, we created an open-source, zero-dependency stdio proxy bridge called mcp-compat that transparently backfills safe default hints (ttlMs: 0, cacheScope: "private"):

In your ~/.claude.json or project MCP config:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "mcp-compat", "--", "uvx", "fastmcp", "run", "server.py"]
    }
  }
}

Or with binaries:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "mcp-compat", "--", "./target/release/my-mcp-server"]
    }
  }
}

It also stabilizes tool and schema ordering across restarts to preserve LLM prompt caching (100% cache hit rate).

Full reproduction test suite and source code available at:
👉 https://github.com/Prognosticate-X/mcp-compat

Hope this helps speed up the fix and unblocks other developers in the meantime!