Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

fix: handle paginated MCP tools/list responses

Open
  • Is something wrong?
#301 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

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

Research direction

Start in raven/agent/tools/mcp.py, where ClientSession.list_tools() is called during MCP connection and discovered tools are registered. Trace the discovery flow and existing test layout, then verify single-page and multi-page servers, repeated cursors, and pagination failures. Done means all pages are registered without infinite loops or silent failures, with unit tests covering the acceptance criteria.

Written by the indexing model from the issue text.

Description

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.

Dominant language
Python
Stars
4.1k
Forks
94
Avg merge
10h 2m
Merged PRs (30d)
376

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

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.

More from EverMind-AI/Raven

All issues in EverMind-AI/Raven

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.