fix(mcp): refresh tools on list_changed notification

[shizhigu]

Fixes #5378.

Why

MCP servers can advertise new or removed tools at runtime via notifications/tools/list_changed. Today MCPServer ignores that notification, so an agent keeps using the stale tool list for the rest of the session — calls to removed tools fail and newly added tools are invisible until restart.

What changed

• MCPServer listens for notifications/tools/list_changed, invalidates its cached list_tools() result, and fans out to subscribed toolsets.
• MCPServer.list_tools() keeps the cache dirty if a notification arrives while a fetch is in flight, so direct callers refetch instead of treating an older snapshot as clean.
• MCPToolset reloads tools in a background task: coalesces duplicate notifications, retries up to 4 attempts with 1s/2s/4s exponential backoff, preserves user filter_tools predicates across reloads, and unregisters on close.
• On terminal reload failure, the toolset fires a callback that AgentActivity bridges to AgentSession.emit("error", ...), so operators can detect that the agent's tool view has gone stale.
• AgentActivity subscribes to Toolset changes, refreshes the realtime session and chat context under _refresh_lock, and inserts an AgentConfigUpdate describing the diff. The public update_tools() path still records a no-op AgentConfigUpdate when the requested tool set is unchanged.
• _close_session cancels refresh tasks and takes _refresh_lock before closing realtime resources, so an in-flight tool publish cannot race with realtime close.
• The publish path is extracted into _publish_tools_change, used by both update_tools() and background refresh.
• _handle_message passes Exception-typed messages through anyio.lowlevel.checkpoint(), matching the MCP SDK default handler so cooperative cancellation propagates.

No public API changes; new callbacks are internal plumbing.

Test plan

Automated

• uv run --extra mcp pytest tests/test_mcp.py
  • 19 passed
• uv run ruff check livekit-agents/livekit/agents/voice/agent_activity.py livekit-agents/livekit/agents/llm/mcp.py tests/test_mcp.py
• make check
• Earlier branch run: uv run --extra mcp pytest tests/test_tools.py
  • 37 passed
• Earlier branch run: make unit-tests
  • 626 passed, 2 skipped; tests/test_room.py setup failed locally because this machine does not have the livekit-server binary on PATH.

New coverage in tests/test_mcp.py includes:

• notification during initial list_tools() does not get missed
• notification during base MCPServer.list_tools() keeps the cache dirty
• toolset reload retries transient failures and surfaces terminal failures
• realtime/chat-context refresh serializes concurrent publishers
• close waits for an in-flight tool publish before closing realtime resources
• public no-op update_tools() still records an audit AgentConfigUpdate
• post-close update_tools() is a no-op
• subscriptions are removed on close
• Exception-typed MCP messages preserve cancellation behavior

End-to-end smoke against a real subprocess MCP server

Wrote a minimal MCP stdio server (using mcp.server.lowlevel.Server + ServerSession.send_tool_list_changed) that mutates its tool list 1s after start, then drove MCPServerStdio + MCPToolset against it in three modes (_RELOAD_RETRY_DELAYS patched to 0/0.1/0.1 for speed):

=== scenario: happy ===
  initial: ['echo']
  after_change_observed: True
  final: ['ping', 'shout']
  reload_failures: []

=== scenario: retry ===
  initial: ['echo']
  after_change_observed: True
  final: ['ping', 'shout']
  reload_failures: []

=== scenario: terminal ===
  initial: ['echo']
  after_change_observed: True
  final: ['echo']
  reload_failures: ['McpError']

Notes

• tests/test_mcp.py is added to the unit-tests make target so it runs in CI.
• Reload uses bounded retry (4 attempts, 1s/2s/4s backoff). On exhaustion the previous tool set is preserved and the failure surfaces via AgentSession's error event.
• _refresh_lock is separate from self._lock because _close_session holds self._lock while cancelling refresh tasks; using one lock for both would deadlock.
• The reload-failure ErrorEvent is tagged with source=<MCPServer> (not the agent) so listeners with multiple MCP servers can identify which one went stale.
• The error event is one-shot per terminal failure; there is no paired "recovered" event when the next reload succeeds. Operators who need recovery confirmation should poll the agent's tool list. Tracked as a follow-up if it becomes painful in practice.
• _publish_tools_change re-checks _closed after acquiring _refresh_lock so a publish queued behind the lock cannot wake into a closing realtime session. _request_tools_reload bails if the toolset has already unsubscribed, closing a snapshot-iteration race in MCPServer._handle_tool_list_changed.
• anyio.lowlevel.checkpoint() runs at the top of _handle_message for every message (not just Exception-typed), matching the MCP SDK default handler so notification bursts don't starve the receive loop of cancellation points.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 5 additional findings.