Skip to content

fix: handle paginated MCP tools/list responses #301

Description

@Yangtze-Seventh

Problem

Raven currently calls ClientSession.list_tools() once when connecting to an MCP server and registers only the tools contained in that single response:

https://github.com/EverMind-AI/Raven/blob/main/raven/agent/tools/mcp.py

MCP tools/list responses are paginated and may include a nextCursor. If a server exposes more tools than its page size, Raven does not follow that cursor, so every tool after the first page is silently omitted.

This is not specific to one integration: any large MCP server that paginates tool discovery can be affected.

Real-world example

vercel-labs/agent-browser exposes a paginated MCP server:

agent-browser mcp --tools all

Its MCP implementation returns at most 64 tools per tools/list page, while the all profile exposes more than 100 tools. Raven therefore registers only the first page and cannot discover or invoke the remaining tools.

The default agent-browser core profile currently fits within one page, so the issue is easy to miss until a larger profile or MCP server is connected.

Expected behavior

Raven should continue requesting tools/list with the returned nextCursor until no cursor remains, then register tools from every page.

Conceptually:

all_tools = []
cursor = None

while True:
    page = await session.list_tools(cursor)
    all_tools.extend(page.tools)

    cursor = page.nextCursor
    if not cursor:
        break

Acceptance criteria

  • Single-page MCP servers continue to work unchanged.
  • Multi-page MCP servers have all tools registered.
  • Pagination stops when nextCursor is absent or None.
  • A repeated cursor cannot cause an infinite loop.
  • Pagination failures produce a visible error rather than silently reporting a complete tool catalog.
  • Unit tests cover both single-page and multi-page discovery.

Why this matters

Without pagination support, large MCP integrations can appear connected successfully while exposing only part of their tool surface. This creates difficult-to-diagnose failures because no connection error is raised and the missing tools simply do not appear in Raven.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions