MCP server pagination

Why MCP tools need their own pagination contract

The MCP protocol paginates list operations natively. When you call resources/list, the response includes an optional nextCursor field; you pass it to the next resources/list call. tools/list works the same way.

Tool calls (tools/call) are different. A single call produces a single CallToolResult. There is no protocol-level continuation — pagination must be implemented as part of the tool's own interface. The tool's inputSchema must accept a cursor, and the tool's response content must include a next cursor, just like a REST endpoint would include a Link: <…>; rel="next" header or a JSON next_page_token field.

The additional challenge: the consumer is an LLM, not code. The LLM reads the tool description to understand what the tool does and how to call it. If the description doesn't explain that nextCursor exists and must be passed back to get more results, the LLM won't paginate — it'll assume the first page is the complete result.

Cursor vs offset pagination

Two common approaches to pagination. Only one is correct for mutable data.

For MCP tools, cursor pagination is almost always the right choice. LLMs traverse results sequentially; they don't need to jump to page 47. And most datasets that need pagination are mutable — skipped or duplicated rows produce incorrect tool results that the LLM cannot detect.

Cursor design: opaque base64-encoded position

The cursor encodes the position in the result set. Keep it opaque to the caller: base64-encode a JSON object containing the anchor column value and sort direction. This lets you change the internal implementation later without breaking existing cursors.

// lib/cursor.ts

interface CursorData {
  lastId: string;
  direction: 'asc' | 'desc';
}

export function encodeCursor(data: CursorData): string {
  return Buffer.from(JSON.stringify(data)).toString('base64url');
}

export function decodeCursor(cursor: string): CursorData {
  try {
    return JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
  } catch {
    throw new Error('Invalid cursor — do not modify cursor values between pages');
  }
}

// The cursor is opaque from the LLM's perspective:
//
// {
//   "items": [...],
//   "nextCursor": "eyJsYXN0SWQiOiJ1c3ItNDIiLCJkaXJlY3Rpb24iOiJhc2MifQ",
//   "hasMore": true,
//   "total": 847
// }
//
// The LLM passes the nextCursor value verbatim in the next call.
// It never inspects or modifies the cursor contents.

Implementing a paginated list tool

// tools/list-records.ts
import { encodeCursor, decodeCursor } from '../lib/cursor.js';
import { db } from '../lib/db.js';

server.tool(
  'list_records',
  {
    cursor: {
      type: 'string',
      description: 'Pagination cursor from the previous call. Omit for the first page.',
      optional: true,
    },
    limit: {
      type: 'number',
      description: 'Maximum records to return (1–100). Default 25.',
      minimum: 1,
      maximum: 100,
      optional: true,
    },
    status: {
      type: 'string',
      enum: ['active', 'archived', 'all'],
      description: 'Filter by record status. Default "active".',
      optional: true,
    },
  },
  async (args) => {
    const limit = Math.min(args.limit ?? 25, 100);
    const status = args.status ?? 'active';

    // Decode cursor (anchor point for keyset query)
    let lastId: string | null = null;
    if (args.cursor) {
      const decoded = decodeCursor(args.cursor);
      lastId = decoded.lastId;
    }

    // Keyset query: WHERE id > lastId ORDER BY id ASC LIMIT limit+1
    // Fetch limit+1 to detect whether there's a next page
    const rows = await db.records.findPage({
      status,
      afterId: lastId,
      limit: limit + 1,
    });

    const hasMore = rows.length > limit;
    const items = hasMore ? rows.slice(0, limit) : rows;

    const nextCursor = hasMore
      ? encodeCursor({ lastId: items[items.length - 1].id, direction: 'asc' })
      : null;

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          items: items.map(r => ({ id: r.id, name: r.name, status: r.status, created_at: r.created_at })),
          nextCursor,
          hasMore,
          pageSize: items.length,
        }),
      }],
    };
  }
);

Writing tool descriptions that teach LLMs to paginate

The most common pagination bug isn't in the server — it's that the LLM stops after the first page because the tool description didn't explain there are more pages. The description must explicitly state the pagination contract.

// Good description — explains the pagination contract to the LLM
const GOOD_DESCRIPTION = `
List records with cursor-based pagination.

Returns up to \`limit\` records (default 25, max 100). If \`hasMore\` is true in
the response, there are additional records available. Call this tool again with
\`cursor\` set to the \`nextCursor\` value from the previous response to retrieve
the next page. Continue until \`hasMore\` is false.

Example multi-page flow:
  1. Call list_records({}) → returns items[0..24], nextCursor="abc", hasMore=true
  2. Call list_records({cursor: "abc"}) → returns items[25..49], nextCursor="def", hasMore=true
  3. Call list_records({cursor: "def"}) → returns items[50..52], nextCursor=null, hasMore=false
`.trim();

// Bad description — LLM won't know to paginate
const BAD_DESCRIPTION = 'List records. Use cursor and limit for pagination.';

The explicit example in the good description is intentional. LLMs reason better with concrete examples than with abstract protocol descriptions. Spelling out the three-step flow gives the model a pattern to follow.

Including totals and page metadata

Decide up front whether to include a total count in the response. Totals require a separate COUNT(*) query and are expensive on large tables. They're also frequently inaccurate for cursored results because the count can change between pages.

Testing pagination correctness

Two bugs are easy to miss: skipped rows (if a record is inserted between pages) and duplicate rows (if a record's sort key changes). Write targeted tests for both.

// test/pagination.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { db } from '../lib/db.js';
import { callTool } from './helpers.js';

describe('list_records pagination', () => {
  beforeEach(async () => {
    await db.records.deleteAll();
    // Insert 55 records with known IDs
    for (let i = 1; i <= 55; i++) {
      await db.records.insert({ id: `rec-${i.toString().padStart(3, '0')}`, name: `Record ${i}` });
    }
  });

  it('returns all 55 records across pages of 20', async () => {
    const allIds: string[] = [];
    let cursor: string | null = null;

    do {
      const result = await callTool('list_records', { limit: 20, cursor: cursor ?? undefined });
      const page = JSON.parse(result.content[0].text);
      allIds.push(...page.items.map((r: { id: string }) => r.id));
      cursor = page.nextCursor;
    } while (cursor !== null);

    expect(allIds).toHaveLength(55);
    expect(new Set(allIds).size).toBe(55); // no duplicates
  });

  it('does not skip records inserted after page 1', async () => {
    const page1 = JSON.parse(
      (await callTool('list_records', { limit: 20 })).content[0].text
    );

    // Insert a new record between pages
    await db.records.insert({ id: 'rec-inserted', name: 'Inserted mid-page' });

    const page2 = JSON.parse(
      (await callTool('list_records', { limit: 20, cursor: page1.nextCursor })).content[0].text
    );

    const allIds = [...page1.items.map((r: { id: string }) => r.id), ...page2.items.map((r: { id: string }) => r.id)];
    expect(new Set(allIds).size).toBe(allIds.length); // no duplicates
  });
});

Further reading

• MCP server tool design — naming, schemas, and output formats for LLMs
• MCP server context propagation — threading user identity through tool calls
• MCP server Resources API — file-like resources with built-in cursor pagination
• MCP server database tools — query builders, ORMs, and safe SQL patterns
• MCP server rate limiting — per-tenant quotas and token bucket strategies
• AliveMCP — continuous protocol monitoring for MCP servers