MCP tools on page 2+ of paginated tools/list dropped after ToolListChangedNotification

Resolved 💬 2 comments Opened May 15, 2026 by jfenal Closed May 17, 2026

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)

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗