:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
fix(replay): preserve recording cursors in mcp query responses (#114941)
posthog[bot]919dff5746fc
diff --git a/products/replay/mcp/prompts/query-session-recordings-list.md b/products/replay/mcp/prompts/query-session-recordings-list.mdindex 0f663bc7e263..7f2b53b0731a 100644--- a/products/replay/mcp/prompts/query-session-recordings-list.md+++ b/products/replay/mcp/prompts/query-session-recordings-list.md@@ -61,6 +61,8 @@ Do not use property filters for time-based filtering. Use the `date_from`/`date_Use `limit` to control page size and `after` (from the previous response's `next_cursor`) for cursor-based pagination.+Each response has `has_next` and `next_cursor`. To get the next page, send the same query again with `after` set to `next_cursor`. When `has_next` is `false`, the response is the last page and `next_cursor` is `null`.+# Response shapeEach recording in results contains:diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.jsonindex 55475f6a3927..afe021780e12 100644--- a/services/mcp/schema/generated-tool-definitions.json+++ b/services/mcp/schema/generated-tool-definitions.json@@ -10863,7 +10863,7 @@"system_prompt_hint": "List persons in a retention acquisition cohort and which intervals they returned in"},"query-session-recordings-list": {- "description": "List session recordings in the project. Returns recording metadata including duration, activity counts, console errors, start URL, and interaction metrics. Use this tool to find, filter, and explore session recordings.\n\nUse 'read-data-schema' to discover available person, session, and event properties for filtering.\n\nExamples of use cases include:\n\n- Find recordings with console errors in the last week\n- Show me recordings from users in a specific country\n- List the longest recordings from today\n- Find recordings where users visited a specific page\n- Show recordings with high activity scores\n- Find recordings for a specific person\n\nCRITICAL: Be minimalist. Only include filters and settings essential to answer the user's question. Default settings are usually sufficient.\n\n# Property filters\n\nUse property filters to narrow results. Only include filters directly relevant to the user's question.\n\nWhen using a property filter, you should:\n\n- **Prioritize properties directly related to the user's query.**\n- **Ensure the correct filter type.** Types: `person`, `session`, `event`, `recording`, `cohort`.\n- **Use `read-data-schema` to discover property names and values** before creating filters.\n\n## Common properties\n\n**Recording** (type: `recording`): `console_error_count`, `click_count`, `keypress_count`, `mouse_activity_count`, `activity_score`. These are built-in metrics, not events.\n\n**Session** (type: `session`): `$session_duration`, `$channel_type`, `$entry_current_url`, `$entry_pathname`, `$is_bounce`, `$pageview_count`.\n\n**Person** (type: `person`): `$geoip_country_code`, `$geoip_city_name`, `email`, and custom person properties.\n\n**Event** (type: `event`): `$current_url`, `$pathname`, `$browser`, `$os`, `$device_type`, `$screen_width`.\n\n**Cohort** (type: `cohort`): scope recordings to persons belonging to a cohort. `key` is always `\"id\"`, `value` is the cohort ID, operator is `in` (or `not_in` to exclude). Example: `{ \"type\": \"cohort\", \"key\": \"id\", \"value\": 42, \"operator\": \"in\" }`. Use `cohorts-list` to find cohort IDs.\n\n## Operators\n\n**String**: `exact`, `is_not`, `icontains`, `not_icontains`, `regex`, `not_regex`, `is_set`, `is_not_set`\n**Numeric**: `exact`, `is_not`, `gt`, `gte`, `lt`, `lte`, `is_set`, `is_not_set`\n**DateTime**: `is_date_exact`, `is_date_before`, `is_date_after`, `is_set`, `is_not_set`\n**Boolean**: `exact`, `is_not`, `is_set`, `is_not_set`\n\n`exact` and `is_not` accept arrays of values. Use `icontains` for URLs, `exact` for enumerated values, `gt`/`lt` for counts.\n\n# Ordering\n\nSort recordings by: `start_time` (default), `duration`, `activity_score`, `console_error_count`, `click_count`, `keypress_count`, `mouse_activity_count`, `active_seconds`, `inactive_seconds`.\n\nDefault direction is `DESC` (newest/highest first).\n\n# Date range\n\n- `date_from`: Relative (`-7d`, `-24h`) or absolute (`2025-01-15`). Default: `-3d`.\n- `date_to`: Relative or absolute. Default: now.\n\nDo not use property filters for time-based filtering. Use the `date_from`/`date_to` fields instead.\n\n# Pagination\n\nUse `limit` to control page size and `after` (from the previous response's `next_cursor`) for cursor-based pagination.\n\n# Response shape\n\nEach recording in results contains:\n\n- `id` — session recording ID\n- `distinct_id` — the person's distinct ID\n- `start_time` / `end_time` — recording time range (ISO 8601)\n- `recording_duration` — length in seconds\n- `active_seconds` / `inactive_seconds` — activity breakdown\n- `click_count`, `keypress_count`, `mouse_activity_count` — interaction counts\n- `console_log_count`, `console_warn_count`, `console_error_count` — console output counts\n- `start_url` — first page URL visited\n- `activity_score` — engagement score (higher = more active)\n- `ongoing` — whether the session is still active\n\n# Deep links to specific recordings\n\nTo link a user to a specific recording, build the URL as `{posthog_base_url}/replay/{id}` using the `id` returned in each result row.\n\nDo not use `/replay/home?sessionRecordingId={id}` — that path takes the user to the replay list with the default filter applied and does not open the recording.\n\n# Examples\n\n## Recent recordings with console errors\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"console_error_count\", \"operator\": \"gt\", \"type\": \"recording\", \"value\": 0 }],\n \"order\": \"console_error_count\"\n}\n```\n\n## Longest recordings today\n\n```json\n{\n \"date_from\": \"-1d\",\n \"filter_test_accounts\": true,\n \"order\": \"duration\",\n \"limit\": 10\n}\n```\n\n## Recordings for a specific person\n\n```json\n{\n \"date_from\": \"-30d\",\n \"person_uuid\": \"01234567-89ab-cdef-0123-456789abcdef\",\n \"filter_test_accounts\": true\n}\n```\n\n## Recordings from mobile users\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"$device_type\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Mobile\"] }]\n}\n```\n\n## Recordings from a cohort of users\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"id\", \"operator\": \"in\", \"type\": \"cohort\", \"value\": 42 }]\n}\n```\n\n## Fetch specific recordings by session ID\n\nWhen you have known `$session_id` values (e.g., from `$exception` events or other event data), use the `session_ids` parameter to fetch those recordings directly:\n\n```json\n{\n \"session_ids\": [\"session-id-1\", \"session-id-2\", \"session-id-3\"]\n}\n```\n\n# Reminders\n\n- Use `filter_test_accounts: true` by default to exclude internal users.\n- Only include property filters directly relevant to the user's question.\n- Default time range is last 3 days. Adjust based on the user's needs.\n- Deep-link to a specific recording as `{posthog_base_url}/replay/{id}`, never `/replay/home?sessionRecordingId={id}`.\n- For detailed analysis of a single recording, use `session-recording-get` with the recording's `id`.\n- For an AI summary of what happened in a recording, read `vision-observations-list` for an existing one, or generate one with `vision-scanners-inline-scan` using `scanner_type: \"summarizer\"` and a `prompt` (the investigating-replay skill carries the exact config the Summarize button uses).\n- **If no recordings are found** or the user asks why recordings aren't being captured, diagnose with `execute-sql`: query `$recording_status`, `$session_recording_start_reason`, `$replay_sample_rate`, and `$sdk_debug_recording_script_not_loaded` from recent events (no `$session_id` filter needed for project-wide issues). Common causes: sampling excluded sessions, recording disabled in project settings, ad blocker blocked the recorder script, or SDK misconfigured.",+ "description": "List session recordings in the project. Returns recording metadata including duration, activity counts, console errors, start URL, and interaction metrics. Use this tool to find, filter, and explore session recordings.\n\nUse 'read-data-schema' to discover available person, session, and event properties for filtering.\n\nExamples of use cases include:\n\n- Find recordings with console errors in the last week\n- Show me recordings from users in a specific country\n- List the longest recordings from today\n- Find recordings where users visited a specific page\n- Show recordings with high activity scores\n- Find recordings for a specific person\n\nCRITICAL: Be minimalist. Only include filters and settings essential to answer the user's question. Default settings are usually sufficient.\n\n# Property filters\n\nUse property filters to narrow results. Only include filters directly relevant to the user's question.\n\nWhen using a property filter, you should:\n\n- **Prioritize properties directly related to the user's query.**\n- **Ensure the correct filter type.** Types: `person`, `session`, `event`, `recording`, `cohort`.\n- **Use `read-data-schema` to discover property names and values** before creating filters.\n\n## Common properties\n\n**Recording** (type: `recording`): `console_error_count`, `click_count`, `keypress_count`, `mouse_activity_count`, `activity_score`. These are built-in metrics, not events.\n\n**Session** (type: `session`): `$session_duration`, `$channel_type`, `$entry_current_url`, `$entry_pathname`, `$is_bounce`, `$pageview_count`.\n\n**Person** (type: `person`): `$geoip_country_code`, `$geoip_city_name`, `email`, and custom person properties.\n\n**Event** (type: `event`): `$current_url`, `$pathname`, `$browser`, `$os`, `$device_type`, `$screen_width`.\n\n**Cohort** (type: `cohort`): scope recordings to persons belonging to a cohort. `key` is always `\"id\"`, `value` is the cohort ID, operator is `in` (or `not_in` to exclude). Example: `{ \"type\": \"cohort\", \"key\": \"id\", \"value\": 42, \"operator\": \"in\" }`. Use `cohorts-list` to find cohort IDs.\n\n## Operators\n\n**String**: `exact`, `is_not`, `icontains`, `not_icontains`, `regex`, `not_regex`, `is_set`, `is_not_set`\n**Numeric**: `exact`, `is_not`, `gt`, `gte`, `lt`, `lte`, `is_set`, `is_not_set`\n**DateTime**: `is_date_exact`, `is_date_before`, `is_date_after`, `is_set`, `is_not_set`\n**Boolean**: `exact`, `is_not`, `is_set`, `is_not_set`\n\n`exact` and `is_not` accept arrays of values. Use `icontains` for URLs, `exact` for enumerated values, `gt`/`lt` for counts.\n\n# Ordering\n\nSort recordings by: `start_time` (default), `duration`, `activity_score`, `console_error_count`, `click_count`, `keypress_count`, `mouse_activity_count`, `active_seconds`, `inactive_seconds`.\n\nDefault direction is `DESC` (newest/highest first).\n\n# Date range\n\n- `date_from`: Relative (`-7d`, `-24h`) or absolute (`2025-01-15`). Default: `-3d`.\n- `date_to`: Relative or absolute. Default: now.\n\nDo not use property filters for time-based filtering. Use the `date_from`/`date_to` fields instead.\n\n# Pagination\n\nUse `limit` to control page size and `after` (from the previous response's `next_cursor`) for cursor-based pagination.\n\nEach response has `has_next` and `next_cursor`. To get the next page, send the same query again with `after` set to `next_cursor`. When `has_next` is `false`, the response is the last page and `next_cursor` is `null`.\n\n# Response shape\n\nEach recording in results contains:\n\n- `id` — session recording ID\n- `distinct_id` — the person's distinct ID\n- `start_time` / `end_time` — recording time range (ISO 8601)\n- `recording_duration` — length in seconds\n- `active_seconds` / `inactive_seconds` — activity breakdown\n- `click_count`, `keypress_count`, `mouse_activity_count` — interaction counts\n- `console_log_count`, `console_warn_count`, `console_error_count` — console output counts\n- `start_url` — first page URL visited\n- `activity_score` — engagement score (higher = more active)\n- `ongoing` — whether the session is still active\n\n# Deep links to specific recordings\n\nTo link a user to a specific recording, build the URL as `{posthog_base_url}/replay/{id}` using the `id` returned in each result row.\n\nDo not use `/replay/home?sessionRecordingId={id}` — that path takes the user to the replay list with the default filter applied and does not open the recording.\n\n# Examples\n\n## Recent recordings with console errors\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"console_error_count\", \"operator\": \"gt\", \"type\": \"recording\", \"value\": 0 }],\n \"order\": \"console_error_count\"\n}\n```\n\n## Longest recordings today\n\n```json\n{\n \"date_from\": \"-1d\",\n \"filter_test_accounts\": true,\n \"order\": \"duration\",\n \"limit\": 10\n}\n```\n\n## Recordings for a specific person\n\n```json\n{\n \"date_from\": \"-30d\",\n \"person_uuid\": \"01234567-89ab-cdef-0123-456789abcdef\",\n \"filter_test_accounts\": true\n}\n```\n\n## Recordings from mobile users\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"$device_type\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Mobile\"] }]\n}\n```\n\n## Recordings from a cohort of users\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"id\", \"operator\": \"in\", \"type\": \"cohort\", \"value\": 42 }]\n}\n```\n\n## Fetch specific recordings by session ID\n\nWhen you have known `$session_id` values (e.g., from `$exception` events or other event data), use the `session_ids` parameter to fetch those recordings directly:\n\n```json\n{\n \"session_ids\": [\"session-id-1\", \"session-id-2\", \"session-id-3\"]\n}\n```\n\n# Reminders\n\n- Use `filter_test_accounts: true` by default to exclude internal users.\n- Only include property filters directly relevant to the user's question.\n- Default time range is last 3 days. Adjust based on the user's needs.\n- Deep-link to a specific recording as `{posthog_base_url}/replay/{id}`, never `/replay/home?sessionRecordingId={id}`.\n- For detailed analysis of a single recording, use `session-recording-get` with the recording's `id`.\n- For an AI summary of what happened in a recording, read `vision-observations-list` for an existing one, or generate one with `vision-scanners-inline-scan` using `scanner_type: \"summarizer\"` and a `prompt` (the investigating-replay skill carries the exact config the Summarize button uses).\n- **If no recordings are found** or the user asks why recordings aren't being captured, diagnose with `execute-sql`: query `$recording_status`, `$session_recording_start_reason`, `$replay_sample_rate`, and `$sdk_debug_recording_script_not_loaded` from recent events (no `$session_id` filter needed for project-wide issues). Common causes: sampling excluded sessions, recording disabled in project settings, ad blocker blocked the recorder script, or SDK misconfigured.","category": "Session replays","feature": "replay","summary": "List session recordings",diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex 51ee00368976..71ceb7e562a8 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -11469,7 +11469,7 @@"system_prompt_hint": "List persons in a retention acquisition cohort and which intervals they returned in"},"query-session-recordings-list": {- "description": "List session recordings in the project. Returns recording metadata including duration, activity counts, console errors, start URL, and interaction metrics. Use this tool to find, filter, and explore session recordings.\n\nUse 'read-data-schema' to discover available person, session, and event properties for filtering.\n\nExamples of use cases include:\n\n- Find recordings with console errors in the last week\n- Show me recordings from users in a specific country\n- List the longest recordings from today\n- Find recordings where users visited a specific page\n- Show recordings with high activity scores\n- Find recordings for a specific person\n\nCRITICAL: Be minimalist. Only include filters and settings essential to answer the user's question. Default settings are usually sufficient.\n\n# Property filters\n\nUse property filters to narrow results. Only include filters directly relevant to the user's question.\n\nWhen using a property filter, you should:\n\n- **Prioritize properties directly related to the user's query.**\n- **Ensure the correct filter type.** Types: `person`, `session`, `event`, `recording`, `cohort`.\n- **Use `read-data-schema` to discover property names and values** before creating filters.\n\n## Common properties\n\n**Recording** (type: `recording`): `console_error_count`, `click_count`, `keypress_count`, `mouse_activity_count`, `activity_score`. These are built-in metrics, not events.\n\n**Session** (type: `session`): `$session_duration`, `$channel_type`, `$entry_current_url`, `$entry_pathname`, `$is_bounce`, `$pageview_count`.\n\n**Person** (type: `person`): `$geoip_country_code`, `$geoip_city_name`, `email`, and custom person properties.\n\n**Event** (type: `event`): `$current_url`, `$pathname`, `$browser`, `$os`, `$device_type`, `$screen_width`.\n\n**Cohort** (type: `cohort`): scope recordings to persons belonging to a cohort. `key` is always `\"id\"`, `value` is the cohort ID, operator is `in` (or `not_in` to exclude). Example: `{ \"type\": \"cohort\", \"key\": \"id\", \"value\": 42, \"operator\": \"in\" }`. Use `cohorts-list` to find cohort IDs.\n\n## Operators\n\n**String**: `exact`, `is_not`, `icontains`, `not_icontains`, `regex`, `not_regex`, `is_set`, `is_not_set`\n**Numeric**: `exact`, `is_not`, `gt`, `gte`, `lt`, `lte`, `is_set`, `is_not_set`\n**DateTime**: `is_date_exact`, `is_date_before`, `is_date_after`, `is_set`, `is_not_set`\n**Boolean**: `exact`, `is_not`, `is_set`, `is_not_set`\n\n`exact` and `is_not` accept arrays of values. Use `icontains` for URLs, `exact` for enumerated values, `gt`/`lt` for counts.\n\n# Ordering\n\nSort recordings by: `start_time` (default), `duration`, `activity_score`, `console_error_count`, `click_count`, `keypress_count`, `mouse_activity_count`, `active_seconds`, `inactive_seconds`.\n\nDefault direction is `DESC` (newest/highest first).\n\n# Date range\n\n- `date_from`: Relative (`-7d`, `-24h`) or absolute (`2025-01-15`). Default: `-3d`.\n- `date_to`: Relative or absolute. Default: now.\n\nDo not use property filters for time-based filtering. Use the `date_from`/`date_to` fields instead.\n\n# Pagination\n\nUse `limit` to control page size and `after` (from the previous response's `next_cursor`) for cursor-based pagination.\n\n# Response shape\n\nEach recording in results contains:\n\n- `id` — session recording ID\n- `distinct_id` — the person's distinct ID\n- `start_time` / `end_time` — recording time range (ISO 8601)\n- `recording_duration` — length in seconds\n- `active_seconds` / `inactive_seconds` — activity breakdown\n- `click_count`, `keypress_count`, `mouse_activity_count` — interaction counts\n- `console_log_count`, `console_warn_count`, `console_error_count` — console output counts\n- `start_url` — first page URL visited\n- `activity_score` — engagement score (higher = more active)\n- `ongoing` — whether the session is still active\n\n# Deep links to specific recordings\n\nTo link a user to a specific recording, build the URL as `{posthog_base_url}/replay/{id}` using the `id` returned in each result row.\n\nDo not use `/replay/home?sessionRecordingId={id}` — that path takes the user to the replay list with the default filter applied and does not open the recording.\n\n# Examples\n\n## Recent recordings with console errors\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"console_error_count\", \"operator\": \"gt\", \"type\": \"recording\", \"value\": 0 }],\n \"order\": \"console_error_count\"\n}\n```\n\n## Longest recordings today\n\n```json\n{\n \"date_from\": \"-1d\",\n \"filter_test_accounts\": true,\n \"order\": \"duration\",\n \"limit\": 10\n}\n```\n\n## Recordings for a specific person\n\n```json\n{\n \"date_from\": \"-30d\",\n \"person_uuid\": \"01234567-89ab-cdef-0123-456789abcdef\",\n \"filter_test_accounts\": true\n}\n```\n\n## Recordings from mobile users\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"$device_type\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Mobile\"] }]\n}\n```\n\n## Recordings from a cohort of users\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"id\", \"operator\": \"in\", \"type\": \"cohort\", \"value\": 42 }]\n}\n```\n\n## Fetch specific recordings by session ID\n\nWhen you have known `$session_id` values (e.g., from `$exception` events or other event data), use the `session_ids` parameter to fetch those recordings directly:\n\n```json\n{\n \"session_ids\": [\"session-id-1\", \"session-id-2\", \"session-id-3\"]\n}\n```\n\n# Reminders\n\n- Use `filter_test_accounts: true` by default to exclude internal users.\n- Only include property filters directly relevant to the user's question.\n- Default time range is last 3 days. Adjust based on the user's needs.\n- Deep-link to a specific recording as `{posthog_base_url}/replay/{id}`, never `/replay/home?sessionRecordingId={id}`.\n- For detailed analysis of a single recording, use `session-recording-get` with the recording's `id`.\n- For an AI summary of what happened in a recording, read `vision-observations-list` for an existing one, or generate one with `vision-scanners-inline-scan` using `scanner_type: \"summarizer\"` and a `prompt` (the investigating-replay skill carries the exact config the Summarize button uses).\n- **If no recordings are found** or the user asks why recordings aren't being captured, diagnose with `execute-sql`: query `$recording_status`, `$session_recording_start_reason`, `$replay_sample_rate`, and `$sdk_debug_recording_script_not_loaded` from recent events (no `$session_id` filter needed for project-wide issues). Common causes: sampling excluded sessions, recording disabled in project settings, ad blocker blocked the recorder script, or SDK misconfigured.",+ "description": "List session recordings in the project. Returns recording metadata including duration, activity counts, console errors, start URL, and interaction metrics. Use this tool to find, filter, and explore session recordings.\n\nUse 'read-data-schema' to discover available person, session, and event properties for filtering.\n\nExamples of use cases include:\n\n- Find recordings with console errors in the last week\n- Show me recordings from users in a specific country\n- List the longest recordings from today\n- Find recordings where users visited a specific page\n- Show recordings with high activity scores\n- Find recordings for a specific person\n\nCRITICAL: Be minimalist. Only include filters and settings essential to answer the user's question. Default settings are usually sufficient.\n\n# Property filters\n\nUse property filters to narrow results. Only include filters directly relevant to the user's question.\n\nWhen using a property filter, you should:\n\n- **Prioritize properties directly related to the user's query.**\n- **Ensure the correct filter type.** Types: `person`, `session`, `event`, `recording`, `cohort`.\n- **Use `read-data-schema` to discover property names and values** before creating filters.\n\n## Common properties\n\n**Recording** (type: `recording`): `console_error_count`, `click_count`, `keypress_count`, `mouse_activity_count`, `activity_score`. These are built-in metrics, not events.\n\n**Session** (type: `session`): `$session_duration`, `$channel_type`, `$entry_current_url`, `$entry_pathname`, `$is_bounce`, `$pageview_count`.\n\n**Person** (type: `person`): `$geoip_country_code`, `$geoip_city_name`, `email`, and custom person properties.\n\n**Event** (type: `event`): `$current_url`, `$pathname`, `$browser`, `$os`, `$device_type`, `$screen_width`.\n\n**Cohort** (type: `cohort`): scope recordings to persons belonging to a cohort. `key` is always `\"id\"`, `value` is the cohort ID, operator is `in` (or `not_in` to exclude). Example: `{ \"type\": \"cohort\", \"key\": \"id\", \"value\": 42, \"operator\": \"in\" }`. Use `cohorts-list` to find cohort IDs.\n\n## Operators\n\n**String**: `exact`, `is_not`, `icontains`, `not_icontains`, `regex`, `not_regex`, `is_set`, `is_not_set`\n**Numeric**: `exact`, `is_not`, `gt`, `gte`, `lt`, `lte`, `is_set`, `is_not_set`\n**DateTime**: `is_date_exact`, `is_date_before`, `is_date_after`, `is_set`, `is_not_set`\n**Boolean**: `exact`, `is_not`, `is_set`, `is_not_set`\n\n`exact` and `is_not` accept arrays of values. Use `icontains` for URLs, `exact` for enumerated values, `gt`/`lt` for counts.\n\n# Ordering\n\nSort recordings by: `start_time` (default), `duration`, `activity_score`, `console_error_count`, `click_count`, `keypress_count`, `mouse_activity_count`, `active_seconds`, `inactive_seconds`.\n\nDefault direction is `DESC` (newest/highest first).\n\n# Date range\n\n- `date_from`: Relative (`-7d`, `-24h`) or absolute (`2025-01-15`). Default: `-3d`.\n- `date_to`: Relative or absolute. Default: now.\n\nDo not use property filters for time-based filtering. Use the `date_from`/`date_to` fields instead.\n\n# Pagination\n\nUse `limit` to control page size and `after` (from the previous response's `next_cursor`) for cursor-based pagination.\n\nEach response has `has_next` and `next_cursor`. To get the next page, send the same query again with `after` set to `next_cursor`. When `has_next` is `false`, the response is the last page and `next_cursor` is `null`.\n\n# Response shape\n\nEach recording in results contains:\n\n- `id` — session recording ID\n- `distinct_id` — the person's distinct ID\n- `start_time` / `end_time` — recording time range (ISO 8601)\n- `recording_duration` — length in seconds\n- `active_seconds` / `inactive_seconds` — activity breakdown\n- `click_count`, `keypress_count`, `mouse_activity_count` — interaction counts\n- `console_log_count`, `console_warn_count`, `console_error_count` — console output counts\n- `start_url` — first page URL visited\n- `activity_score` — engagement score (higher = more active)\n- `ongoing` — whether the session is still active\n\n# Deep links to specific recordings\n\nTo link a user to a specific recording, build the URL as `{posthog_base_url}/replay/{id}` using the `id` returned in each result row.\n\nDo not use `/replay/home?sessionRecordingId={id}` — that path takes the user to the replay list with the default filter applied and does not open the recording.\n\n# Examples\n\n## Recent recordings with console errors\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"console_error_count\", \"operator\": \"gt\", \"type\": \"recording\", \"value\": 0 }],\n \"order\": \"console_error_count\"\n}\n```\n\n## Longest recordings today\n\n```json\n{\n \"date_from\": \"-1d\",\n \"filter_test_accounts\": true,\n \"order\": \"duration\",\n \"limit\": 10\n}\n```\n\n## Recordings for a specific person\n\n```json\n{\n \"date_from\": \"-30d\",\n \"person_uuid\": \"01234567-89ab-cdef-0123-456789abcdef\",\n \"filter_test_accounts\": true\n}\n```\n\n## Recordings from mobile users\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"$device_type\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Mobile\"] }]\n}\n```\n\n## Recordings from a cohort of users\n\n```json\n{\n \"date_from\": \"-7d\",\n \"filter_test_accounts\": true,\n \"properties\": [{ \"key\": \"id\", \"operator\": \"in\", \"type\": \"cohort\", \"value\": 42 }]\n}\n```\n\n## Fetch specific recordings by session ID\n\nWhen you have known `$session_id` values (e.g., from `$exception` events or other event data), use the `session_ids` parameter to fetch those recordings directly:\n\n```json\n{\n \"session_ids\": [\"session-id-1\", \"session-id-2\", \"session-id-3\"]\n}\n```\n\n# Reminders\n\n- Use `filter_test_accounts: true` by default to exclude internal users.\n- Only include property filters directly relevant to the user's question.\n- Default time range is last 3 days. Adjust based on the user's needs.\n- Deep-link to a specific recording as `{posthog_base_url}/replay/{id}`, never `/replay/home?sessionRecordingId={id}`.\n- For detailed analysis of a single recording, use `session-recording-get` with the recording's `id`.\n- For an AI summary of what happened in a recording, read `vision-observations-list` for an existing one, or generate one with `vision-scanners-inline-scan` using `scanner_type: \"summarizer\"` and a `prompt` (the investigating-replay skill carries the exact config the Summarize button uses).\n- **If no recordings are found** or the user asks why recordings aren't being captured, diagnose with `execute-sql`: query `$recording_status`, `$session_recording_start_reason`, `$replay_sample_rate`, and `$sdk_debug_recording_script_not_loaded` from recent events (no `$session_id` filter needed for project-wide issues). Common causes: sampling excluded sessions, recording disabled in project settings, ad blocker blocked the recorder script, or SDK misconfigured.","category": "Session replays","feature": "replay","summary": "List session recordings",diff --git a/services/mcp/src/api/client.ts b/services/mcp/src/api/client.tsindex bed7048e117d..d7483648c7c3 100644--- a/services/mcp/src/api/client.ts+++ b/services/mcp/src/api/client.ts@@ -1610,12 +1610,16 @@ export class ApiClient {columns?: unknown[] | nullformatted_results?: stringwarnings?: (DataWarehouseSyncWarning | AccessControlFilterWarning)[] | null+ has_next?: boolean+ next_cursor?: string | null}> => {return this.request<{results: unknowncolumns?: unknown[] | nullformatted_results?: stringwarnings?: (DataWarehouseSyncWarning | AccessControlFilterWarning)[] | null+ has_next?: boolean+ next_cursor?: string | null}>({method: 'POST',path: `/api/environments/${projectId}/query/`,diff --git a/services/mcp/src/tools/query-wrapper-factory.ts b/services/mcp/src/tools/query-wrapper-factory.tsindex f80bb4a65cf5..b33ccffb2015 100644--- a/services/mcp/src/tools/query-wrapper-factory.ts+++ b/services/mcp/src/tools/query-wrapper-factory.ts@@ -242,6 +242,10 @@ export function createQueryWrapper<T extends ZodObjectAny>(config: QueryWrapperC// column names are the only way to read each cell....(Array.isArray(data.columns) && Array.isArray(data.results) ? { columns: data.columns } : {}),...(data.warnings ? { warnings: data.warnings } : {}),+ // Cursor-paginated queries (e.g. RecordingsQuery) need these for the caller to request the next page.+ ...(typeof data.has_next === 'boolean'+ ? { has_next: data.has_next, next_cursor: data.next_cursor ?? null }+ : {}),}if (isTraceQuery) {return compactTraceResponse(response, traceDetail, effectiveOutputFormat)diff --git a/services/mcp/tests/unit/query-wrapper-factory.test.ts b/services/mcp/tests/unit/query-wrapper-factory.test.tsindex 4ed2c8881e24..4b99a86b9329 100644--- a/services/mcp/tests/unit/query-wrapper-factory.test.ts+++ b/services/mcp/tests/unit/query-wrapper-factory.test.ts@@ -640,6 +640,48 @@ describe('createQueryWrapper warnings', () => {})})+describe('createQueryWrapper cursor pagination', () => {+ const schema = z.object({ kind: z.string(), after: z.string().optional() })++ it('forwards has_next and next_cursor, and sends after on the next request', async () => {+ const runQuery = vi+ .fn()+ .mockResolvedValueOnce({ results: [{ id: 'a' }], has_next: true, next_cursor: 'cursor-1' })+ .mockResolvedValueOnce({ results: [{ id: 'b' }], has_next: false, next_cursor: null })+ const context = {+ api: {+ query: vi.fn().mockReturnValue({ runQuery }),+ getProjectBaseUrl: vi.fn().mockReturnValue('http://localhost:8010/project/1'),+ },+ stateManager: { getProjectId: vi.fn().mockResolvedValue('1') },+ } as unknown as Context+ const tool = createQueryWrapper({ name: 'test', schema, kind: 'RecordingsQuery' })()++ const first = (await tool.handler(context, { kind: 'RecordingsQuery' })) as any+ expect(first).toMatchObject({ has_next: true, next_cursor: 'cursor-1' })++ const second = (await tool.handler(context, { kind: 'RecordingsQuery', after: first.next_cursor })) as any+ expect(runQuery.mock.calls[1]?.[0].query.after).toBe('cursor-1')+ expect(second).toMatchObject({ results: [{ id: 'b' }], has_next: false, next_cursor: null })+ })++ it('omits the keys for queries that do not paginate by cursor', async () => {+ const context = {+ api: {+ query: vi.fn().mockReturnValue({ runQuery: vi.fn().mockResolvedValue({ results: [] }) }),+ getProjectBaseUrl: vi.fn().mockReturnValue('http://localhost:8010/project/1'),+ },+ stateManager: { getProjectId: vi.fn().mockResolvedValue('1') },+ } as unknown as Context+ const tool = createQueryWrapper({ name: 'test', schema, kind: 'HogQLQuery' })()++ const result = (await tool.handler(context, { kind: 'HogQLQuery' })) as any++ expect(result).not.toHaveProperty('has_next')+ expect(result).not.toHaveProperty('next_cursor')+ })+})+describe('createQueryWrapper columns', () => {const schema = z.object({ breakdownBy: z.string() })