docs: document pagination (#491)

For #442

Author: findleyr

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.

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.