What it does
The `prompts/list` method is sent by the MCP client to the server to retrieve the full catalogue of prompt templates the server makes available. Before calling this method, the client must confirm during capability negotiation (the `initialize` handshake) that the server declared `prompts` in its `capabilities` object. If the server did not advertise this capability, the client must not send `prompts/list`, and doing so will result in a `MethodNotFound` (-32601) or capability error response. The request may include an optional `cursor` string for pagination. The server responds with a `prompts` array of `Prompt` objects — each containing at minimum a `name` and optionally a `description` and `arguments` schema — plus an optional `nextCursor` field. When `nextCursor` is present, the client must issue another `prompts/list` call passing that cursor as `cursor` to retrieve the next page. Pagination is cursor-based and opaque; clients must not attempt to parse or construct cursors manually. Clients should re-fetch the full prompt list (from the first page) whenever the server emits a `notifications/prompts/list_changed` notification. Because this notification arrives asynchronously, there is a brief window where the cached list is stale — clients should treat any `prompts/get` call that returns an unknown prompt name as a signal to re-enumerate immediately rather than surface a hard error to the user.
When to use
After initialize or on list_changed.
When NOT to use
Per render — cache.
Notes
Capability gating is mandatory
A client must only call `prompts/list` if the server advertised `{"prompts": {}}` (or equivalent) in its `capabilities` during `initialize`. Servers that receive this call without having declared the capability should return a JSON-RPC error with code -32601 (MethodNotFound). SDKs like the official TypeScript and Python MCP libraries will throw a capability-check error on the client side before the request is even sent.
Cursor-based pagination, not offset-based
The `cursor` value returned in `nextCursor` is a server-defined opaque token. Never derive page numbers or offsets from it. Pass it verbatim in the next request. When the response omits `nextCursor` (or it is `null`), the list is exhausted. Some servers return all prompts in a single page and never emit `nextCursor` — your pagination loop must handle both cases.
Stale-list race after list_changed
The `notifications/prompts/list_changed` notification does not carry a diff — it is a pure invalidation signal. Re-fetch from cursor `undefined` (the first page) on receipt. If a `prompts/get` returns -32602 (InvalidParams) for an unknown prompt name between the notification and the re-fetch completing, treat that as a transient stale-cache condition rather than a permanent error.
Error codes to handle
Beyond -32601 for missing capability, watch for -32603 (InternalError) when the server's prompt registry fails to load, and -32602 (InvalidParams) when a malformed or expired cursor is passed. Expired cursors can occur if the server restarts between paginated calls; the safe recovery is to restart enumeration from the beginning.
Caching and refresh strategy
Cache the prompt list in memory keyed by server connection identity. Invalidate the entire cache (not individual entries) on `notifications/prompts/list_changed`. Avoid re-fetching on every user interaction — the list is typically stable across a session. If your client supports multiple concurrent servers, maintain separate caches per server and avoid merging prompt namespaces without a server-identity prefix to prevent name collisions.
Request parameters
| Name | Type | Purpose |
|---|---|---|
| cursor | string? | Pagination cursor. |
Response fields
| Name | Type | Purpose |
|---|---|---|
| prompts | Prompt[] | Available prompts. |
| nextCursor | string? | Pagination. |
Examples
List prompts
{ "method": "prompts/list" }