Cursor

A cursor is an opaque identifier provided by an MCP server to facilitate pagination. It represents the server's state or a pointer to the next set of items in a sequence.

Implementation Details

• Opaqueness: Clients should treat cursors as opaque strings. They should not attempt to parse or derive meaning from the cursor's content.
• Expiration: Depending on the server implementation, cursors may have a limited TTL (Time To Live).
• Usage: Cursors are passed in the params object of list-style methods like resources/list, prompts/list, and tools/list.

JSON-RPC Context

In an MCP result:

{
  "method": "resources/list",
  "params": {
    "cursor": "eyJvZmZzZXQiOjEwMH0="
  }
}

Questions & Answers

What is a "Cursor" in the context of the Model Context Protocol?

In MCP, a cursor is an opaque string identifier provided by a server to help a client navigate through paginated result sets, representing a specific pointer to the next set of items.

Why should MCP clients treat cursors as opaque?

Clients should treat cursors as opaque because their internal structure depends on the server's specific implementation. Parsing them could lead to errors if the server changes its internal paging logic.

In which MCP methods are cursors typically used?

Cursors are used in "list-style" methods where responses might be too large for a single message, such as resources/list, prompts/list, and tools/list.