Pagination¶

Protocol-level list calls¶

FastMCP handles tools/list / prompts/list / resources/list / resources/templates/list pagination automatically. Neither libtmux-mcp nor the agent needs to do anything: the server chooses a sensible page size, encodes the cursor in an opaque base64 blob, and replays state from it. Callers only need to thread through nextCursor if they consume the raw MCP protocol.

Tool-level result paging on search_panes¶

One libtmux-mcp tool owns its own paging surface because a single tmux server can carry tens of thousands of pane lines:

• search_panes readonly returns a SearchPanesResult wrapper with matches, truncated, truncated_panes, total_panes_matched, offset, and limit.

• Agents detect truncated=True and re-call with a higher offset to page through the match set.

This is application-level paging (not MCP-cursor pagination) — the agent decides how many matches it needs and when to stop.

Tool-level observation cursors on capture_since¶

capture_since readonly also has a cursor parameter, but it is not a pagination cursor. The first call captures the current visible pane and returns an opaque observation checkpoint. Follow-up calls pass that cursor back to receive only rows written or rewritten after the checkpoint while tmux still retains the needed history.

Because the cursor points into live tmux grid state, it has different failure modes from protocol pagination:

• If the pane output scrolls into retained history, the cursor can still produce an exact delta.

• If tmux clears or trims the needed history, the response sets lines_missed=True and returns a conservative current visible capture with a fresh cursor.

• If the pane dies or is respawned, the cursor is invalid because it would otherwise point at a different process’s terminal state.

This is application-level observation, not a stable collection scan. Use it to reduce repeated pane reads, not to page through search matches.