Manage guides and surveys with Amplitude MCP

The Amplitude MCP server exposes guides and surveys through run_amp, a general-purpose tool that runs amp CLI commands against the Amplitude Developer API. Ask ChatGPT, Claude, Cursor, or another MCP client to list, inspect, create, update, or archive a guide or survey, and the client runs the matching guides or surveys command. Writes change a draft only. Publishing happens in the Amplitude UI.

Use run_amp when you want an AI client to read or edit guide and survey configuration in conversation. For a scripted pipeline, call the Developer API endpoints directly. To design a guide visually, preview it, or publish it, use the Amplitude UI.

Connect the Amplitude MCP server to your client before you run any of these commands. Amplitude MCP Server covers setup for each client. These commands work in both the standard and EU residency regions. Point your client at the server URL for the region that holds your Amplitude data, listed in Regions.

Guides and surveys have no dedicated MCP tool. Earlier server versions exposed list_guides_surveys and get_guide_or_survey, and neither tool exists now. Ask for the same outcome in plain language, and your client routes the request to run_amp.

Available commands

Command	What it does	Required scope
`guides list`, `surveys list`	Return a page of items, with filters for platform, creator, and date.	`guides:read`, `surveys:read`
`guides get`, `surveys get`	Return one item, including steps, variants, and targeting.	`guides:read`, `surveys:read`
`guides create`, `surveys create`	Create an unpublished draft.	`guides:write`, `surveys:write`
`guides update`, `surveys update`	Edit metadata, page targeting, and content variants on the draft.	`guides:write`, `surveys:write`
`guides archive`, `surveys archive`	Archive an unpublished item.	`guides:write`, `surveys:write`

Guides and surveys run on an Experiment feature flag, but you don't need a flags:* scope to use these commands. Amplitude also checks your access to the project on every call.

How your client calls run_amp

run_amp takes the subcommand in command and every option in flags:

json

{ "command": ["guides", "list"], "flags": { "project": "12345", "limit": "10" } }

These rules shape what your client can send:

Flag names drop their leading dashes, so --created-by becomes "created-by".
The MCP session pins base-url, env, region, token, profile, json, and yes, so your client can't set them.
Archive commands need allowDestructive: true on the tool call.
Your client discovers commands and flags with help, help guides, or help guides create rather than guessing a name.

List and inspect guides and surveys

guides list and surveys list return a page of items with cursor pagination. Filter with platform, created-after, created-before, created-by, and include-archived. Set limit to control page size, which defaults to 50 and caps at 200. The list commands don't support full-text search or custom sort orders yet.

Each item carries the fields you rank or filter on in a prompt:

Field	Description
`status`	Derived rollout state: `draft`, `testing`, `published`, `scheduled`, `experiment-running`, or `archived`.
`priority`	Trigger precedence, from 4 (urgent) down to 1 (low).
`key`	Feature flag key that controls delivery. Join it to SDK-tracked guide and survey events.
`start_at`, `end_at`	Scheduled start and end of the live flag, or `null` when nothing is scheduled.
`url`	Admin URL for the item in Amplitude.
`latest_version`	Version number that `update` requires.

Priority decides which experience shows when more than one guide or survey is eligible on the same page. Setup and target covers how Amplitude resolves priority ties.

guides get and surveys get return the live published version by default. Add include-unpublished-changes to read the latest draft instead. Your client also uses that flag to read the latest_version an update requires.

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.

Show me the full configuration for guide 15731.

What pages does this guide target?

What steps does this product tour include?

Can users snooze or dismiss this guide?

Create a guide or survey

guides create and surveys create always produce an unpublished draft. title is the only required field. You can also set description, platform, priority, and a single content variant with its steps.

Create rejects the reserved control key. Amplitude builds the item on a disabled draft flag that targets all users, then returns an admin url in the response. Open that URL to set the audience.

Create a guide called "Welcome tour" in project 12345 with a single modal step.

Update a guide or survey

guides update and surveys update edit the draft. On a published item, your live users keep seeing the published version until someone publishes the draft in the Amplitude UI.

Every update needs latest-version, the version your client read from a get with include-unpublished-changes. A stale value returns 409.

json

{
  "command": ["guides", "update"],
  "flags": {
    "project": "12345",
    "guide": "15731",
    "latest-version": "7",
    "title": "Welcome tour v2"
  }
}

Update writes page-URL targeting (page-target-segments), trigger and lifecycle rules, snooze and dismiss behavior, the step counter, and content variants.

When an update sends variants, it must list every existing variant by id with its unchanged variant key. Amplitude replaces the variant list instead of merging it, so any variant your client leaves out disappears from the draft. Within a variant, your client can add, edit, reorder, or remove steps. Guides and surveys built in the block builder store their layout in content_v2 and reject variant edits.

Rename survey 678 in project 12345 to "NPS Q4".

Raise the priority of guide 15731 to urgent.

Archive a guide or survey

Archive works on unpublished items only. An item counts as published while its backing flag is enabled, unless it's in test mode with no schedule, so an enabled guide whose schedule already ended still counts as published. Archiving a published item returns 409 with error_code: cannot_archive_published, including when your client passes dry-run. Unpublish the item in Amplitude first.

Check first with dry-run, which validates the request without changing anything:

json

{
  "command": ["guides", "archive"],
  "flags": { "project": "12345", "guide": "15731", "dry-run": true }
}

Then run the archive itself, which needs allowDestructive: true:

json

{
  "command": ["guides", "archive"],
  "flags": { "project": "12345", "guide": "15731" },
  "allowDestructive": true
}

An item that's already archived returns 404.

Check whether guide 15731 in project 12345 can be archived. Dry run first.

What stays in the Amplitude UI

Area	Behavior through MCP
Publishing, scheduling, test mode	Not available. Publish, schedule, and send test instrumentation in Amplitude.
Audience targeting (`flag_config`)	Read-only. Create returns an admin `url`, and you set audience and rollout there.
Tags	Read-only. An update that sends `tags` returns `400`.
Experiment variants	Read-only. Amplitude derives them when an experiment backs the item.
Status fields	Read-only. Amplitude derives `status` and `status_description` from the flag and schedule.

Limitations

Retrying a write isn't safe. Each write carries an Idempotency-Key, but v1 has no replay store behind it, so a retried create makes a second guide or survey. If a write times out or fails ambiguously, read the item back before you try again.

The latest-version check runs before the write rather than atomically with it. The check reduces lost updates between concurrent writers, but it doesn't prevent them.

Two more constraints apply:

Users who sign in through enterprise-managed auth can't read guides and surveys through MCP.
Reads go through the Developer API, which adds roughly 2 to 5 seconds per read.

Common workflows

Audit live guides and surveys

List everything that isn't archived, then narrow to what users see right now:

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

Find the item with a list command, then pull its full configuration:

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 and web experiences separately:

What iOS surveys are currently published?

Which web guides were created in the last 30 days?

Draft a guide, then finish it in Amplitude

Create the draft in conversation, then open the admin URL to set audience and publish:

Create a guide called "Billing refresh announcement" in project 12345.

Show me the admin URL for that guide.

Was this helpful?