feat: add paginated list decorators for prompts, resources, and tools #1286

maxisbey · 2025-08-20T13:14:21Z

Summary

This PR adds pagination support for listing prompts, resources, and tools using cursor-based pagination as defined in the MCP spec.

Design Evolution

Initial Implementation (Updated)

Originally, this PR introduced separate paginated decorators (list_prompts_paginated, list_resources_paginated, list_tools_paginated) to maintain backward compatibility. The rationale was:

Backward compatibility: Modifying existing decorators would break existing code
Clean separation: Users could opt-in to pagination
Type safety: Different signatures for paginated vs non-paginated handlers

Current Implementation (After Discussion)

Based on feedback and discussion, the implementation has evolved to use unified decorators with automatic callback inspection:

Single list_prompts(), list_resources(), and list_tools() decorators handle both paginated and non-paginated callbacks
Uses the new accepts_cursor() function to inspect callback signatures at runtime
Maintains full backward compatibility while allowing pagination support
Cleaner API with no need for separate decorator methods

How It Works

The decorators now automatically detect whether a callback accepts a cursor parameter:

# Non-paginated (existing code continues to work)
@server.list_resources()
async def list_resources() -> list[Resource]:
    return [...]

# Paginated (new capability)
@server.list_resources()
async def list_resources(cursor: Cursor | None) -> ListResourcesResult:
    return ListResourcesResult(resources=[...], nextCursor="...")

Changes

Add accepts_cursor() function for callback signature inspection
Modify list_prompts(), list_resources(), and list_tools() decorators to support both signatures
Add comprehensive unit tests for pagination and signature detection
Add examples demonstrating pagination usage
Tool cache properly maintained for both paginated and non-paginated modes

Test plan

Unit tests pass for all three decorators with both signatures
Tests verify cursor passthrough for both None and string values
Function inspection tests cover various callback signatures
Backward compatibility verified with existing non-paginated handlers
Manually tested via the inspector and with example client code

🤖 Generated with Claude Code

👨 Below generated by the human, Max Isbey

Manual testing

I spun up the MCP inspector and ran the example pagination server in both stdio mode and SSE mode. Below is some testing evidence using the SSE mode:

Clicking "List More Resources" correctly lists all 30 resources:

Note: this works for prompts and tools as well

Requesting a resource works:

Running the pagination client example code works listing all 30 resources:

jerome3o-anthropic

Can we have a some docs with examples? not sure if we have good docs for the lowlevel api but some usage examples would be great (if not just to help with reviewing).

Otherwise this looks good to me. happy with the separate functions to avoid breaking changes. keen to know how you think we should approach this in the high level interface.

maxisbey · 2025-08-20T15:37:50Z

Can we have a some docs with examples? not sure if we have good docs for the lowlevel api but some usage examples would be great (if not just to help with reviewing).

Otherwise this looks good to me. happy with the separate functions to avoid breaking changes. keen to know how you think we should approach this in the high level interface.

Updated the docs, added example code, and included testing in the PR desription

.pre-commit-config.yaml

src/mcp/server/lowlevel/server.py

Kludex

Backward compatibility: Modifying the existing decorators to require a cursor parameter in the callback would break existing uses of these decorators.

You can make it optional, can't you?

Add list_prompts_paginated, list_resources_paginated, and list_tools_paginated decorators to support cursor-based pagination for listing endpoints. These decorators: - Accept a cursor parameter (can be None for first page) - Return the respective ListResult type directly - Maintain backward compatibility with existing non-paginated decorators - Update tool cache for list_tools_paginated Also includes simplified unit tests that verify cursor passthrough. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

Apply automatic formatting from ruff to ensure code meets project standards: - Remove trailing whitespace - Adjust line breaks for consistency - Format function arguments according to line length limits

- Create mcp_simple_pagination example server demonstrating all three paginated endpoints - Add pagination snippets for both server and client implementations - Update README to use snippet-source pattern for pagination examples - Move mutually exclusive note to blockquote format for better visibility - Complete example shows tools, resources, and prompts pagination with different page sizes

The previous change to run tools directly (without uv run) broke the CI pipeline because the tools are installed in uv's virtual environment which isn't in PATH during pre-commit execution. Reverting to use `uv run --frozen` ensures the tools are found both locally and in CI environments.

Kludex · 2025-09-01T10:51:06Z

examples/servers/simple-pagination/mcp_simple_pagination/server.py

+            ],
+        )
+
+    if transport == "sse":


Why are we doing this every time?

Just following the pattern of all the other sample servers

I'd prefer to leave this as is, and maybe chnage in a different PR dedicated to simplifying the example servers or something if that's alright with you?

Kludex · 2025-09-01T10:53:38Z

src/mcp/server/lowlevel/func_inspection.py

+    if method:
+        params.pop("self", None)
+        params.pop("cls", None)


We shouldn't rely on parameter names.

Oh fair, turns out this isn't needed anyway as inspect.signature.parameters doesn't contain these by default. Updated the unit tests to reflect this.

Kludex · 2025-09-01T10:57:35Z

src/mcp/server/lowlevel/server.py

+                cursor_func = cast(Callable[[types.Cursor | None], Awaitable[types.ListToolsResult]], func)
+
+                async def cursor_handler(req: types.ListToolsRequest):
+                    result = await cursor_func(req.params.cursor if req.params is not None else None)


Would it make sense to pass the ListToolRequest instead? What does that object contains?

I'm on my phone only this week.

Because then you, as a user don't need to type it as Cursor | None.

Hmm well the only thing in the ListToolsRequest is the cursor. Unless you think in the future there's a chance more would be added to it?

My point is more that it makes more sense to receive a request as parameter.

But answering the question... Yes, if something is added in the future, it will be there.

Alrighty, changed from pasing cursors to passing request objects

maxisbey requested a review from a team as a code owner August 20, 2025 13:14

maxisbey requested review from jerome3o-anthropic, felixweinberger and jspahrsummers August 20, 2025 13:14

jerome3o-anthropic requested changes Aug 20, 2025

View reviewed changes

maxisbey force-pushed the feat/list-pagination branch from 91fa584 to 9d72703 Compare August 20, 2025 14:02

maxisbey force-pushed the feat/list-pagination branch from 66ee42f to 83d4890 Compare August 20, 2025 15:43

jerome3o-anthropic self-requested a review August 20, 2025 15:44

jerome3o-anthropic previously approved these changes Aug 20, 2025

View reviewed changes

maxisbey dismissed jerome3o-anthropic’s stale review via 550e3fe August 21, 2025 13:47

maxisbey force-pushed the feat/list-pagination branch 3 times, most recently from 70435e5 to 5d823c8 Compare August 21, 2025 13:51

jerome3o-anthropic self-requested a review August 21, 2025 14:02

jerome3o-anthropic previously approved these changes Aug 21, 2025

View reviewed changes

maxisbey enabled auto-merge (squash) August 21, 2025 14:02

maxisbey requested a review from pcarleton August 21, 2025 14:17

Kludex reviewed Aug 21, 2025

View reviewed changes

.pre-commit-config.yaml Show resolved Hide resolved

src/mcp/server/lowlevel/server.py Outdated Show resolved Hide resolved

Kludex requested changes Aug 21, 2025

View reviewed changes

maxisbey dismissed jerome3o-anthropic’s stale review via 47c3f19 August 21, 2025 16:33

maxisbey and others added 5 commits August 27, 2025 10:07

style: apply ruff formatting to pass pre-commit checks

002ffa3

Apply automatic formatting from ruff to ensure code meets project standards: - Remove trailing whitespace - Adjust line breaks for consistency - Format function arguments according to line length limits

chore: clean up pre-commit to use tools directly over uv with --frozen

1a4c179

switch pagination to single decorator with callback inspection

2b2e80c

maxisbey force-pushed the feat/list-pagination branch from 47c3f19 to 2b2e80c Compare August 27, 2025 14:16

maxisbey requested a review from Kludex August 27, 2025 14:19

maxisbey added 2 commits August 27, 2025 10:47

Merge branch 'main' into feat/list-pagination

7954284

Kludex reviewed Sep 1, 2025

View reviewed changes

chore: clean up inspection code to remove redundant param inspection

a32e396

maxisbey requested a review from Kludex September 1, 2025 12:56

feat: change to passing requests instead of cursors for pagination

0532ec3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add paginated list decorators for prompts, resources, and tools #1286

feat: add paginated list decorators for prompts, resources, and tools #1286

maxisbey commented Aug 20, 2025 •

edited

Loading

Uh oh!

jerome3o-anthropic left a comment

Uh oh!

maxisbey commented Aug 20, 2025

Uh oh!

Uh oh!

Uh oh!

Kludex left a comment

Uh oh!

Kludex Sep 1, 2025

Uh oh!

maxisbey Sep 1, 2025

Uh oh!

maxisbey Sep 1, 2025

Uh oh!

Kludex Sep 1, 2025

Uh oh!

maxisbey Sep 1, 2025

Uh oh!

Kludex Sep 1, 2025

Uh oh!

Kludex Sep 1, 2025

Uh oh!

maxisbey Sep 1, 2025

Uh oh!

Kludex Sep 1, 2025

Uh oh!

maxisbey Sep 1, 2025

Uh oh!

Uh oh!

feat: add paginated list decorators for prompts, resources, and tools #1286

Are you sure you want to change the base?

feat: add paginated list decorators for prompts, resources, and tools #1286

Conversation

maxisbey commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Design Evolution

Initial Implementation (Updated)

Current Implementation (After Discussion)

How It Works

Changes

Test plan

Manual testing

Clicking "List More Resources" correctly lists all 30 resources:

Requesting a resource works:

Running the pagination client example code works listing all 30 resources:

Uh oh!

jerome3o-anthropic left a comment

Choose a reason for hiding this comment

Uh oh!

maxisbey commented Aug 20, 2025

Uh oh!

Uh oh!

Uh oh!

Kludex left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

maxisbey commented Aug 20, 2025 •

edited

Loading