pagination

fastmcp.utilities.pagination

Pagination utilities for MCP list operations.

Functions

paginate_sequence

paginate_sequence(items: Sequence[T], cursor: str | None, page_size: int) -> tuple[list[T], str | None]

Paginate a sequence of items.

Args:

• items: The full sequence to paginate.
• cursor: Optional cursor from a previous request. None for first page.
• page_size: Maximum number of items per page.

Returns:

• Tuple of (page_items, next_cursor). next_cursor is None if no more pages.

Raises:

• ValueError: If the cursor is invalid.

Classes

CursorState

Internal representation of pagination cursor state.

The cursor encodes the offset into the result set. This is opaque to clients per the MCP spec - they should not parse or modify cursors.

Methods:

encode

encode(self) -> str

Encode cursor state to an opaque string.

decode

decode(cls, cursor: str) -> CursorState

Decode cursor from an opaque string.

Raises:

• ValueError: If the cursor is invalid or malformed.