---
title: Manage guides and surveys with Amplitude MCP
description: "Use the run_amp tool in the Amplitude MCP server to list, inspect, create, update, and archive guides and surveys from an AI client."
product: general
lang: en
last_updated: 2026-10-29
token_estimate: 2530
---
# Manage guides and surveys with Amplitude MCP

The [Amplitude MCP server](https://amplitude.com/docs/amplitude-ai/amplitude-mcp) exposes guides and surveys through `run_amp`, a general-purpose tool that runs `amp` CLI commands against the [Amplitude Developer API](https://amplitude.com/docs/apis/developer). 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.

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

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](https://amplitude.com/docs/apis/developer) 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](https://amplitude.com/docs/amplitude-ai/amplitude-mcp) 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](https://amplitude.com/docs/amplitude-ai/amplitude-mcp#regions).

> **Note:**
>
> 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](https://amplitude.com/docs/guides-and-surveys/setup-and-target#priority) 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.

> **Warning:**
>
> 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

> **Warning:**
>
> 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.

> **Note:**
>
> 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](https://amplitude.com/docs/amplitude-ai/amplitude-mcp/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.