claude-code - 💡(How to fix) Fix [BUG] MCP deferred tool activation — client tool list doesn't refresh after notifications/tools/list_changed [2 comments, 3 participants]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

When an MCP server activates deferred tools mid-session (e.g. graph8's g8_tool_search returns an activated_session_tools list and the server emits notifications/tools/list_changed), Claude's client-side tool list does not always pick up the newly-activated tools. Calling one of them returns Tool 'X' not found even though the server is ready to serve it. A manual refresh from the user fixes it.

Reproduction: Connect a server with deferred tools (graph8 MCP, ~200 tools, ~30 visible by default). Ask Claude to do something requiring a hidden tool category (e.g. "list workflow node types"). Claude calls g8_tool_search which activates the workflow tools server-side. Claude immediately calls g8_workflow_list_node_types → fails with "tool not found." User manually refreshes the tool list → next call succeeds.

What Should Happen?

Claude's client should consume notifications/tools/list_changed before the next tool invocation, or the activator's response payload should trigger a synchronous refresh.

Error Messages/Logs

Error: 'graph8:g8_workflow_list_node_types' has not been loaded yet. You do not have the correct parameter names for this tool. Call tool_search with a relevant query first to load the tool definition and discover the correct parameters, then call it with the right parameter names. You tried parameters: [detail] — these may be incorrect.

Steps to Reproduce

Connect a server with deferred tools (graph8 MCP, ~200 tools, ~30 visible by default). Ask Claude to do something requiring a hidden tool category (e.g. "list workflow node types"). Claude calls g8_tool_search which activates the workflow tools server-side. Claude immediately calls g8_workflow_list_node_types → fails with "tool not found." User manually refreshes the tool list → next call succeeds.

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

No response

Claude Code Version

2.1.122

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

No response