Second Brain

claude-code-deferred-tool-registry-is-frozen-at-session-star

3 min read

Claude Code deferred-tool registry is frozen at session start — mid-session MCP cutovers require a fresh session

The trap

When an MCP server is upgraded mid-session (rebuild + container restart + new tools published), the Claude Code session that was already running BEFORE the cutover will NOT see the new deferred tool schemas — even though /health and direct tools/list curl confirm the new tools are live server-side. The session’s deferred-tool registry was populated when the session opened and is NOT refreshed by container restarts.

Symptoms

  • ToolSearch for the new tool name returns “No matching deferred tools found”
  • OR — worse — the OLD schema for an upgraded tool is what gets loaded, with new optional params absent (silent rejection of new args, or args getting routed to additionalProperties: true and ignored)
  • Direct curl /mcp confirms the new schema is live → confirms it’s a CLIENT-side cache issue, not a server-side gap

Confirmed examples (operator session 2026-05-06)

  1. fivetran-mcp v18.x → v19.1.2 — added daily_sync_time + schedule_type as top-level params on modify_connector. Live session’s cached schema lacked the new top-level fields; operator passed them nested under config (additionalProperties:true) → Fivetran returned 200 OK and silently ignored the unknown nested key. Connector unchanged.
  2. tableau-mcp v5.x → v6.0.4 — added update_extract_refresh_task + create_extract_refresh_task. Live session’s ToolSearch returned “No matching deferred tools found” for both names. Server-side /mcp tools/list confirmed both present.
  3. salesforce-mcp v7.0.2 → v7.1.0 — added 9 new P1-P6 operator-intent tools. Live session’s deferred registry was frozen at v7.0.2 launch and didn’t surface the new tools. Required a fresh session to access them.

Resolution (operator-side, ~30 sec)

  1. Open a fresh Claude Code session — the deferred-tool registry rebuilds on session open and inherits the upgraded MCP server’s current tools/list.
  2. (Optional belt-and-suspenders) — refresh the relevant Custom Connector in Claude Desktop before opening the new session.

Anti-patterns — do NOT

  • ❌ Try harder with the stale schema (passing new params nested in config etc.) — they get silently ignored OR routed wrong
  • ❌ Bypass with curl scripts using stored creds — violates tool-ambiguity protocol
  • ❌ Assume the server is broken because the session can’t see new tools — verify server-side first via direct /health + /mcp tools/list curl

How to tell quickly

If you suspect this:

# Compare what the session sees vs. what the server actually exposes
curl -s https://<server>.arjtech.in/health | jq '.tools, .version'
curl -s https://<server>.arjtech.in/mcp -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'

If server count > what your session can resolve via ToolSearch → it’s session staleness. Open fresh session.

Why this matters

The frozen-registry behavior is invisible — there’s no warning, no version skew banner. Operator confidently calls upgraded tooling, gets “tool not found” or silent argument-drop, and starts debugging the wrong layer (server thinks it’s a server bug, dev thinks it’s a feature gap, etc.). Costs 30-60 min per occurrence to re-diagnose.

Time-saving claim

Catching this in <2 min instead of 30-60 min ≈ 30+ min saved per recurrence. With the rate of MCP server upgrades on this stack (≥1 per week), this is one of the higher-frequency operator gotchas on the Claude Code platform itself.

  • feedback_tool_ambiguity_protocol.md — flag + stop, don’t bypass
  • Decisions log entries 2026-05-06 (DSR pipeline reschedule re-attempt) and 2026-05-06 (System Admin Clone tightening on v7.1.0)

Graph View

Backlinks