From 49d45a809707cbf19808614e5208012bed849da7 Mon Sep 17 00:00:00 2001
From: Robert Findley <rfindley@google.com>
Date: Thu, 18 Sep 2025 13:31:54 -0400
Subject: [PATCH] docs: document pagination (#491)

For #442
---
 docs/server.md              | 26 +++++++++++++++++++++++++-
 internal/docs/server.src.md | 26 +++++++++++++++++++++++++-
 2 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/docs/server.md b/docs/server.md
index e6af5d9..4d6192f 100644
--- a/docs/server.md
+++ b/docs/server.md
@@ -121,4 +121,28 @@ func Example_prompts() {
 
 ### Pagination
 
-<!-- TODO -->
+Server-side feature lists may be
+[paginated](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/pagination),
+using cursors. The SDK supports this by default.
+
+**Client-side**: The `ClientSession` provides methods returning
+[iterators](https://go.dev/blog/range-functions) for each feature type.
+These iterators are an `iter.Seq2[Feature, error]`, where the error value
+indicates whether page retrieval failed.
+
+- [`ClientSession.Prompts`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Prompts)
+  iterates prompts.
+- [`ClientSession.Resource`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Resource)
+  iterates resources.
+- [`ClientSession.ResourceTemplates`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.ResourceTemplates)
+  iterates resource templates.
+- [`ClientSession.Tools`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Tools)
+  iterates tools.
+
+The `ClientSession` also exposes `ListXXX` methods for fine-grained control
+over pagination.
+
+**Server-side**: pagination is on by default, so in general nothing is required
+server-side. However, you may use
+[`ServerOptions.PageSize`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.PageSize)
+to customize the page size.
diff --git a/internal/docs/server.src.md b/internal/docs/server.src.md
index 07ed6cb..32f80e9 100644
--- a/internal/docs/server.src.md
+++ b/internal/docs/server.src.md
@@ -48,4 +48,28 @@ Set [`ClientOptions.PromptListChangedHandler`](https://pkg.go.dev/github.com/mod
 
 ### Pagination
 
-<!-- TODO -->
+Server-side feature lists may be
+[paginated](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/pagination),
+using cursors. The SDK supports this by default.
+
+**Client-side**: The `ClientSession` provides methods returning
+[iterators](https://go.dev/blog/range-functions) for each feature type.
+These iterators are an `iter.Seq2[Feature, error]`, where the error value
+indicates whether page retrieval failed.
+
+- [`ClientSession.Prompts`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Prompts)
+  iterates prompts.
+- [`ClientSession.Resource`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Resource)
+  iterates resources.
+- [`ClientSession.ResourceTemplates`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.ResourceTemplates)
+  iterates resource templates.
+- [`ClientSession.Tools`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Tools)
+  iterates tools.
+
+The `ClientSession` also exposes `ListXXX` methods for fine-grained control
+over pagination.
+
+**Server-side**: pagination is on by default, so in general nothing is required
+server-side. However, you may use
+[`ServerOptions.PageSize`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.PageSize)
+to customize the page size.