stacklok / stacklok/toolhive

vMCP backend queries do not follow pagination cursors (silent truncation past 1000 tools)

Open
#5,771 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
2.2k
Forks
300
Avg merge
1d 15h
Merged PRs (30d)
184

Description

Context

While writing regression tests for the mcp-go → go-sdk migration (#5742), a pagination regression was discovered.

Finding

pkg/vmcp/client/client.go queryTools (around line 700) does a single ListTools with ListToolsRequest{} — no cursor loop. The go-sdk paginates tools/list at DefaultPageSize=1000, so backends with >1000 tools are silently truncated.

The same issue applies to queryResources and queryPrompts.

Impact: vMCP servers aggregating backends with >1000 tools will silently drop tools beyond the first page. Non-cursor-following clients see an incomplete tool set.

Regression test coverage

  • TestRegression_Over1000Tools_CompleteSetReceived in test/integration/vmcp/pagination_regression_test.go — skipped test with t.Skip("vMCP does not follow pagination cursors; see gap-analysis V1 / follow-up issue"). Serves as a regression anchor for when cursor-following is implemented.

MCP spec reference

MCP 2025-11-25 §"Pagination": tools/list supports cursor; servers MAY paginate. Clients must follow nextCursor.

Acceptance criteria

  • queryTools, queryResources, and queryPrompts should follow pagination cursors until exhausted
  • The skipped test should be un-skipped and pass
  • A backend exposing >1000 tools should return the complete set through vMCP

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in pkg/vmcp/client/client.go at queryTools, queryResources, and queryPrompts, then read the pagination regression anchor in test/integration/vmcp/pagination_regression_test.go. Use TestRegression_Over1000Tools_CompleteSetReceived to verify that cursor-based results are complete, unskip it, and confirm the test passes for backends with more than 1000 tools.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
backend-api-design, testing
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.