Ten rows and a cursor beat a thousand rows and a timeout.

Your app may have thousands of projects. An agent usually needs a few recognizable choices and a way to continue. Give it a compact page with just an ID and a name, then let it follow the next call when the task needs more.

{ "name": "list_projects", "arguments": { "limit": 2 } }

{ "name": "list_projects", "arguments": { "cursor": "00000000-0000-4000-8000-000000000002", "limit": 2 } }

{ "name": "list_projects", "arguments": { "cursor": "00000000-0000-4000-8000-000000000002", "limit": 2 } }

null

Illustrative results for a page size of two. The same cards and continuation are represented in the Markdown and JSON versions.

Chumbo’s collection helpers validate the requested page size, project compact items, and bound the encoded result. You still choose the query, ordering, cursor meaning, and application permissions.

Check the installed package in your application before editing. Install the matching Chumbo skill so your coding agent has the package’s instructions. If this is your first MCP, begin with the authenticated-projects recipe linked below.

npx chumbo --version
npx chumbo skill install

Use one stable, unique ordering key for both the query and cursor. This example orders UUID project IDs and resumes after the last returned ID. The extra row tells the result helper whether another page exists.

import {
  collectionInputSchema, collectionOutputSchema, collectionResult, errorResult,
  type SupabaseMcpContext, type SupabaseMcpServer,
} from "chumbo";
import { z } from "zod";

const projectCard = z.object({ id: z.string().uuid(), name: z.string() });

export function registerCapabilities(server: SupabaseMcpServer, ctx: SupabaseMcpContext) {
  server.registerTool("list_projects", {
    description: "Browse your projects in ID order. Follow next_call for another page.",
    inputSchema: collectionInputSchema({
      defaultLimit: 5, maxLimit: 20, cursorSchema: z.string().uuid(),
    }),
    outputSchema: collectionOutputSchema(projectCard),
    annotations: { readOnlyHint: true },
  }, async ({ limit, cursor }) => {
    let query = ctx.supabase.from("projects")
      .select("id, name").order("id").limit(limit + 1);
    if (cursor) query = query.gt("id", cursor);
    const { data, error } = await query
      .overrideTypes<{ id: string; name: string }[], { merge: false }>();
    if (error) return errorResult("Could not load your projects.", "Retry; if this continues, contact your app's support.");

    return collectionResult({
      items: data ?? [], limit, maxLimit: 20, hasMore: false,
      itemSchema: projectCard,
      project: ({ id, name }) => ({ id, name }),
      cursorFor: ({ id }) => id,
      tool: "list_projects", maxBytes: 4000, mode: "hybrid",
      render: ({ items }) => items.length
        ? items.map(p => `- ${p.name} (${p.id})`).join("\n")
        : "No projects are visible on this page. Open your app to create a project, or restart list_projects without a cursor.",
      onOversizedItem: () => "Open this project in your app for its full details.",
    });
  });
}

The hybrid result has two deliberate consumers: a short list for the agent and typed items plus continuation for clients. If only an agent needs the result, choose text mode and omit outputSchema. Avoid adding full rows or large descriptions to both representations.

Run the generated checks, then keep your local function running. Use your app’s fixture setup to create separate projects for two users. The generated tests alone do not prove this pagination contract or your application’s permissions.

deno task --config supabase/functions/mcp/deno.json check
deno task --config supabase/functions/mcp/deno.json test

supabase start
npx chumbo dev --function mcp

npx @modelcontextprotocol/inspector

In MCP Inspector, choose Streamable HTTP, enter the exact Local MCP URL printed by chumbo dev, and configure Alice’s bearer access token. Call list_projects with limit: 2. Follow the returned next_call arguments until it is null. Reconnect as Bob and repeat. Use local tokens only with the local endpoint.

A clear next_call makes continuation possible. The agent should continue only when the user’s task needs more results. For full project details, add an application-owned detail tool or Resource that checks the same caller’s access.