88831b46f6
Move the documentation that had grown to 3000+ lines in README.md onto https://ruby.sdk.modelcontextprotocol.io and slim the README down to a quick start and feature overview, following the Python SDK layout: - Add 21 server pages as the docs/_server/ collection (overview plus transports, discovery, tools, prompts, resources, roots, sampling, elicitation, multi round-trip results, notifications, notification subscriptions, cancellation, progress, ping, completions, logging, pagination, server context, configuration, and custom methods), 8 client pages as the docs/_client/ collection (overview, transports, lifecycle, multi round-trip results, cancellation, ping, pagination, and authorization), and 3 extension pages as the docs/_extensions/ collection (overview, capability extensions, and MCP Apps, following the Extensions Overview recommendation that SDK documentation list the supported extensions) - one page per topic, ordered to match the sidebar of the 2026-07-28 specification, with the client-side APIs (pinging, cancelling, and paginating from MCP::Client) documented under Building Clients - Add top-level Examples and Protocol Versions pages after Installation, linking the runnable examples in examples/ and summarizing the supported protocol versions, the era model, and client negotiation - Render the three sections as just-the-docs collections, which list every page beneath a plain category heading in the sidebar with no folding, and serve every page at an extensionless URL under /server/, /client/, and /extensions/, matching the sibling SDK documentation sites - Replace docs/building-servers.md and docs/building-clients.md with redirects to the new section overview pages via jekyll-redirect-from, redirect the previously published /installation.html to its extensionless URL, fold their content that was missing from README.md into the new pages, and update the Tool argument keys reference comment in lib/mcp/server.rb to the relocated Tools page - Reduce README.md to the badges, a compact feature overview in the Python SDK style, installation instructions, a stdio server and client quick start, and a License section, using absolute URLs for the remaining repository links so they resolve on rubygems.org - Adapt formatting where GitHub rendering habits break on the site: convert the numbered "three ways to define" lists into headings, since kramdown restarts numbering at 1 when code blocks split list items, convert GitHub-style alerts into just-the-docs callouts with the SEP-2260 server-to-client association note raised to a red warning, merge the duplicated Exception Reporting and Configuration Block Data sections into the Configuration page, and relocate the Streamable HTTP settings that were nested under the Logging section into the Transports page - Refresh the migrated content against the current implementation: correct stale claims and broken samples the README carried, note on each session-era feature how it relates to the modern lifecycle of MCP 2026-07-28, and point spec links at the latest revision, keeping deliberate 2025-11-25 pins for pages the modern revision removed - Style the site after the Rails API documentation palette (red links and accents on neutral surfaces) with matching light and dark color schemes, center the sidebar and content as one block, add a Previous/Next footer pager following the sidebar order, open external links in a new tab, and serve the MCP logo as the favicon Every code block and heading from the previous README was verified to have a home in the new docs pages or the slimmed README before the reduction; a few samples were corrected rather than copied, as noted above.
3.6 KiB
| layout | title | nav_order |
|---|---|---|
| default | Pagination | 7 |
Pagination
Servers may paginate tools/list, prompts/list, resources/list, and resources/templates/list responses
per the MCP pagination utility.
Cursor tokens are opaque to clients: the server decides page size, and the client follows nextCursor until the server omits it.
Iterating Pages
MCP::Client exposes list_tools, list_prompts, list_resources, and list_resource_templates.
Each call issues exactly one */list JSON-RPC request and returns exactly one page - not the full collection.
The returned result object (MCP::Client::ListToolsResult etc.) exposes the page items and the next cursor
as method accessors; a meta accessor also mirrors the response's _meta field:
client = MCP::Client.new(transport: transport)
cursor = nil
loop do
page = client.list_tools(cursor: cursor)
page.tools.each { |tool| process(tool) }
cursor = page.next_cursor
break unless cursor
end
The same pattern applies to list_prompts (page.prompts), list_resources (page.resources), and
list_resource_templates (page.resource_templates). next_cursor is nil on the final page.
Because a single call returns a single page, how many items come back depends on the server's page_size configuration:
Server page_size |
client.list_tools(cursor: nil) |
|---|---|
| Not set (default) | Returns every item in one response. next_cursor is nil. |
Set to N |
Returns the first N items. next_cursor is set for continuation. |
If your application needs the complete collection regardless of how the server is configured, either loop on
next_cursor as shown above, or use the whole-collection methods described below.
Fetching the Complete Collection
client.tools, client.resources, client.resource_templates, and client.prompts auto-iterate
through all pages and return a plain array of items, guaranteeing the full collection regardless
of the server's page_size setting. When a server paginates, they issue multiple JSON-RPC round
trips per call. Two guards keep that loop finite: it stops when the server returns a nextCursor
it has already sent, and it stops after max_pages pages.
tools = client.tools # => Array<MCP::Client::Tool> of every tool on the server.
MCP::Client.new accepts an optional max_pages: keyword that caps how many pages these methods
will walk. It defaults to 1_000; a server that keeps offering a fresh nextCursor past that
point raises MCP::Client::PaginationLimitError rather than being followed indefinitely. Raise it
if you legitimately expect more pages than that.
Use these when you want the complete list; use list_tools(cursor:) etc. when you need
fine-grained iteration (e.g. to stream-process pages without loading everything into memory).
Cache Hints
Per SEP-2549, list and read results can carry cache hints telling clients how long a result stays fresh (ttlMs)
and whether shared intermediaries may cache it (cacheScope); see
List Result Caching on the server page for how they are emitted.
On the client, the values are surfaced on the paginated result structs as ttl_ms and cache_scope:
page = client.list_tools
page.ttl_ms # => 60000 (nil when the server sent no hint)
page.cache_scope # => "private"
Server Side
Enabling pagination with page_size: is documented on the server Pagination page.