claude code mcp spec compliance — list_changed, progress, sampling, messages, and async gaps

[yigitkonur]

hey team, consolidating a bunch of scattered issues (many closed in circular duplicate loops) into one place. hopefully this is useful as a single reference for mcp spec features that are missing or partially working.

list_changed notifications (server → claude code)

2.1.0 changelog says "added support for MCP list_changed notifications" — and it partially landed, but there are still gaps:

tools/list_changed:

• works across prompt turns (tool added → next prompt sees it)
• does NOT work within the same turn — if a tool is registered mid-turn, claude tries to call it and gets Error: No such tool available (Capture MCP Tools Changed notifications - notifications/prompts/list_changed notifications #4118 comments confirm)
• startup race condition: if tools register asynchronously after init (common with service discovery, plugin systems, agent registries), claude queries the tool list before they exist and the notification doesn't reliably trigger a re-fetch. mcp server authors have to add artificial delays (Feature Request: Support MCP tools/list_changed notification for dynamic tool discovery #24195)
• someone decompiled cli.js and confirmed the zod schema existed but setNotificationHandler was never called ([Bug] MCP tool list not refreshed on notifications/tools/list_changed event #13646) — unclear if 2.1.0 fully fixed this

prompts/list_changed:

• three separate issues reported this (Claude Code doesn't respond to MCP notifications/prompts/list_changed for dynamic command updates #2722, [BUG] Resource autocomplete cannot dynamically change or update. #3326, Add support for MCP notifications/prompts/list_changed notifications #4094) and they all got closed in a circular duplicate loop (2722 → dup of 4094, 4094 → dup of 2722, 3326 → dup of 2722). no open issue remained
• new slash commands from mcp servers don't appear without restart

resources/list_changed:

• dynamically added resources don't show up in @ autocomplete ([BUG] Resource autocomplete cannot dynamically change or update. #3326)

outgoing notifications (claude code → server)

roots/list_changed:

• /add-dir mid-session updates claude code's internal state but never sends notifications/roots/list_changed to connected mcp servers (/add-dir does not send notifications/roots/list_changed to MCP servers #26663)
• servers that validate paths against workspace roots silently break
• gemini cli handles this correctly, for reference

other mcp spec features not implemented

looked through the spec and existing issues — here's what else is missing:

mcp spec feature	spec link	status in claude code	related issues
notifications/progress (progress tokens)	spec	ignored — no progress display for long-running tools	#4157
notifications/message (server → client)	spec	received but never displayed to user or injected into context	#3174
sampling (server requests llm inference)	spec	not implemented	#1785
async/background tool execution	—	all mcp tool calls are sequential and blocking	#1759, #8712, #1478

context on why this matters

the agent sdk already has a sophisticated notification system for its own subagent lifecycle. looking at the published types in @anthropic-ai/claude-agent-sdk:

// task lifecycle events
SDKTaskStartedMessage    → { subtype: 'task_started', task_id, description }
SDKTaskProgressMessage   → { subtype: 'task_progress', task_id, usage: { total_tokens, tool_uses, duration_ms } }
SDKTaskNotificationMessage → { subtype: 'task_notification', task_id, status: 'completed'|'failed'|'stopped', summary }

// hook events
TeammateIdleHookInput    → { teammate_name, team_name }
TaskCompletedHookInput   → { task_id, task_subject, teammate_name?, team_name? }

this is great — start, progress, complete, with usage tracking and hook integration. the infrastructure for handling async notifications clearly exists and works well.

the mcp spec defines similar primitives (progress notifications, messages, list_changed, sampling) that would let third-party mcp servers participate in the same kind of workflows. implementing these would make the whole ecosystem stronger and let mcp servers do things like:

• report progress on long-running operations without blocking
• dynamically register tools based on runtime context (game state, service discovery, plugin loading)
• hot-reload prompts and resources during development without restarting
• request llm inference through the client's existing auth/subscription

prior issues (for reference)

issue	topic	current state
#2722	prompts/list_changed	closed (circular dup)
#3326	resources/list_changed + autocomplete	closed (dup of #2722)
#4094	prompts/list_changed	closed (circular dup of #2722)
#4118	tools/list_changed	open, 14 comments, partially addressed
#13646	tools/list_changed source analysis	closed (dup of #4118)
#15667	tools/list_changed repro	closed (dup of #4118)
#24195	tools/list_changed race condition	closed (dup of #4118)
#26663	roots/list_changed (outgoing)	open
#1478	notification-driven auto-resume	closed
#1759	background tasks via mcp	closed
#1785	sampling support	open
#2799	elicitation support	open
#3174	notifications/message display	closed
#4157	progress notifications	closed
#8712	background mcp tool execution	closed

would love to see these gaps closed over time. happy to help test or provide repro cases for any of these. thanks for building claude code — it's genuinely great to work with, and getting mcp spec parity would make it even better.

[github-actions]

Found 3 possible duplicate issues:

1. [Bug] MCP tool list not refreshed on notifications/tools/list_changed event #13646
2. Claude Code does not respond to MCP notifications/tools/list_changed #15667
3. Claude Code doesn't respond to MCP notifications/prompts/list_changed for dynamic command updates #2722

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.