Guides and Surveys MCP tools

The Amplitude MCP server provides two tools for working with Guides and Surveys. Connect the server from ChatGPT, Claude, Cursor, or another MCP client to discover, review, and analyze your guides and surveys with natural language.

These tools return structured Guides and Surveys configuration, including published state, priority, targeting, triggers, and step content. The general-purpose search tool can still find guides and surveys, but list_guides_surveys and get_guide_or_survey expose the same concepts you manage in the Amplitude UI.

Available tools

Tool	Description
`list_guides_surveys`	List guides and surveys in a project, with filters by type, platform, creator, date range, and archived status. Each result includes status, priority, and creator metadata.
`get_guide_or_survey`	Retrieve full details for a single guide or survey by ID, including status, priority, variants, step content, targeting rules, and trigger configuration.

list_guides_surveys

Use list_guides_surveys to discover and compare guides and surveys across a project. This tool is best for overview and summary questions: what is live, what is scheduled, and what is in an experiment.

Parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	The project ID (appId) to list guides and surveys for.
`types`	array	No	Filter by type. Accepts `"GUIDE"`, `"SURVEY"`, or both. Defaults to both.
`platform`	string	No	Filter by target platform: `web`, `ios`, `android`, `react-native`, `desktop`, or `flutter`. The `web` value also matches items with no platform set.
`createdAfter`	string (ISO 8601)	No	Lower bound on creation timestamp (inclusive).
`createdBefore`	string (ISO 8601)	No	Upper bound on creation timestamp (inclusive).
`createdBy`	string	No	Filter by the email or login ID of the user who created the item.
`includeArchived`	boolean	No	Include archived items. Defaults to `false`.
`limit`	integer	No	Number of items per page. Defaults to 50, maximum 200.
`cursor`	string	No	Pagination cursor from a previous response's `nextCursor`. Omit for the first page.

Response fields

Each item in the response includes metadata you can filter or rank in your prompt:

Field	Description
`status`	Lifecycle state: `draft`, `testing`, `published`, or `scheduled`.
`priority`	Relative importance when multiple experiences are eligible: Urgent, High, Medium, or Low.
`createdBy`	Email or login ID of the user who created the item.
`title`	Display name of the guide or survey.
`type`	`GUIDE` or `SURVEY`.

Priority determines which experience displays when more than one guide or survey is eligible on the same page. Refer to Setup and target for how Amplitude resolves priority ties.

Example prompts

What are the published guides with the highest priority in my project?

What guides and surveys are currently live?

Which surveys are running on iOS?

Show me all guides created by alice@example.com in Q1 2025.

List all archived surveys.

get_guide_or_survey

Use get_guide_or_survey to deep-dive into a single guide or survey after finding it with list_guides_surveys. This tool returns the full configuration: status, priority, variant configurations, step content, page targeting rules, trigger settings, and rollout state.

Parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	The project ID (appId) the guide or survey belongs to.
`nudgeId`	string	Yes	The ID of the guide or survey to retrieve.

Example prompts

Show me the full configuration for guide 15731.

Is the onboarding survey live or scheduled?

What pages does this guide target?

What steps does this product tour include?

Can users snooze or dismiss this guide?

Common workflows

Audit active nudges

List all published and experiment-running guides and surveys to review what users are seeing:

List all non-archived guides and surveys in project 574019.

Which guides are in an experiment right now?

Review targeting and content before a launch

After finding an item with list_guides_surveys, use get_guide_or_survey to verify its targeting rules and step content before publishing:

Show me the page targeting and trigger configuration for survey 101.

What copy appears in each step of guide 15728?

Platform-specific audits

Filter by platform to review mobile or web experiences separately:

What iOS surveys are currently published?

Which web guides were created in the last 30 days?

Connect the MCP server

To use these tools, connect the Amplitude MCP server to your AI editor. Refer to Amplitude MCP Server for setup instructions.

Was this helpful?