claude-code - 💡(How to fix) Fix MCP tools on page 2+ of paginated tools/list dropped after ToolListChangedNotification

Bug

When an MCP server paginates its tools/list response (using nextCursor per the MCP spec), Claude Code only fetches the first page. Tools on subsequent pages return Error: No such tool available when called, with no warning that tools were dropped.

This is especially visible with dynamic tool loading: when a server sends notifications/tools/list_changed after registering new tools, Claude Code re-fetches the tool list but again only reads page 1.

Reproduction

1. MCP server using FastMCP 3.2.4 with list_page_size=20
2. Server starts in zero-cost discovery mode (6 bootstrap tools — fits on 1 page)
3. User calls workspace_discover(["slides"]) which registers 23 more tools (29 total) and sends ToolListChangedNotification
4. Claude Code re-fetches tools/list — gets 20 tools on page 1 with a nextCursor for page 2
5. Page 2 (9 tools) is never fetched

Result: 15 of 23 product tools work. The 9 tools on page 2 (gslides_set_content, gslides_update_text, gslides_replace_all_text, etc.) return "No such tool available" when called.

Expected: Claude Code follows nextCursor to fetch all pages, making all 29 tools available.

Evidence

Tools in registration order with page boundary at 20:

Page 1 (fetched):
  1-6:   bootstrap tools (workspace_*)
  7-20:  gslides_create .. gslides_batch_format  ← all work

Page 2 (NOT fetched):
  21: gslides_set_content         ← "No such tool available"
  22: gslides_set_paragraph_bullets
  23: gslides_clear_paragraph_bullets
  24: gslides_set_table_cell_text
  25: gslides_update_text         ← "No such tool available"
  26: gslides_replace_all_text    ← "No such tool available"
  27: gslides_export_pdf
  28: gslides_export_pptx
  29: gslides_extract_links

Server-side verification confirms all 29 tools are registered correctly — await server.mcp.list_tools() returns all of them.

Workaround

Remove list_page_size from the FastMCP constructor so all tools return on a single page (no pagination).

Environment

• Claude Code: 2.1.142
• FastMCP: 3.2.4
• MCP transport: stdio
• OS: Fedora 43 (Linux 6.19.14)