# StepsKit MCP — capabilities & limits

> What you can and can't ask the StepsKit MCP to do today: create AND edit unpublished tours (steps, content, behavior settings, visibility/targeting, theme/brand colors), create AND edit tooltips, surveys, and scheduled announcements, install the embed, switch between the projects you own — but not yet publish or analytics.

*Source: https://stepskit.com/docs/ai-agents/capabilities*

The MCP exposes a curated subset of the tour model. Knowing the boundary up front
saves you from asking for something it can't do yet. Your agent knows this list
too — it can call `get_capabilities` to answer accurately instead of guessing.

> **Note**
>
> This page mirrors the live `get_capabilities` tool. If they ever disagree, the
> tool is the source of truth.

## Available now

- List the projects your token can reach and choose which one to work on (`list_projects`, `select_project`) — an account-scoped token spans every project you own, a project-scoped one is pinned to a single project. Most project-level tools also take a one-off `project` argument; see [Pick a project](/docs/ai-agents/connect.md#pick-a-project)
- List your tours and read a tour's full editable state (settings + steps)
- Create unpublished tours with ordered steps — each step accepts the full editable surface (advance-on-click, backdrop, multi-page URL pattern / navigate URL), so complete tours are authorable in one call
- Callout steps (anchored to a CSS selector) and modal steps (centered card, no selector)
- Disambiguate a target by its **text** when CSS alone can't: append one trailing `:has-text("…")` hint to any target selector (e.g. `#toolbar button:has-text("Export")`). Case-insensitive substring match. A selector that matches several elements renders nothing and gets flagged in the dashboard, so this is how you pin one of several identical elements
- Edit a tour's name and behavior settings: navigation buttons, button labels, progress counter, keyboard control, overlay-click behavior, highlight padding, auto-navigate-to-next-page, and a completion redirect (`completionUrl` — send the visitor to a page when they finish the tour via Done; never fires on dismiss)
- Edit a tour's visibility: audience targeting rules, page URL pattern, minimum screen width, show-once frequency, and trigger (auto-play on page load, manual via the JS API, or on click of an element matching a CSS selector)
- Target dynamic routes (IDs in the URL like `/items/<id>/edit`) by wildcarding the ID segment — `/items/*` — and derive that pattern from a concrete URL with `suggest_url_pattern`
- Set your project-wide default themes — one each for tours, tooltips, announcement banners, and survey cards — and override a single tour's or tooltip's theme (popover/text/button colors, title/body font sizes, per-element alignment — title, body, and the button row each get their own — button corner radius, overlay color & opacity, progress indicator, and highlight border for tours; the flat 4-color banner/card theme for announcements and surveys, to match your brand)
- Edit, add, delete, and reorder steps — title, body, target selector, type, position, backdrop, page URL pattern, an explicit per-step navigate URL (the literal destination page for multi-page auto-navigate), plus per-step button labels/visibility, progress, alignment, advance-on-click (advance the tour when the user clicks the step's highlighted target), and per-step appearance overrides (title/body font size, per-element alignment, button corner radius — layered over the tour theme)
- List and read your tooltips
- Create unpublished tooltips — an anchor selector, popover title/body, indicator style (a question/info/dot/pulse glyph or a NEW/BETA text badge), placement, how the popover opens (on hover or on click), and an optional CTA (open a link, start a tour, or fire a custom event)
- Edit and delete tooltips — content, indicator, open trigger (hover or click), CTA, visibility (audience targeting, URL pattern, minimum screen width, show-once frequency), and a per-tooltip popover theme (layered over your project's tooltip default)
- List and read your NPS surveys
- Create and edit unpublished NPS surveys — the recommend question, a selectable rating scale (NPS 0-10, numeric 1-5, or emoji), scale labels, an optional open-text follow-up, thank-you message, which bottom corner the card appears in, dismissible, re-survey window (in days), visibility (audience targeting, URL pattern, minimum screen width), and the card colors (background, text, button — layered over your project's survey-card default)
- List and read your announcements
- Create, edit, and delete unpublished announcements — a top or bottom banner strip (edge or floating) with a title, body, an optional CTA (open a link or fire a custom event), an optional lucide/emoji icon, banner & button corner radii, a schedule window (start/end — run a time-boxed banner), visibility (audience targeting, URL pattern, minimum screen width, show-once frequency), and the banner colors (background, text, button — layered over your project's announcement default)
- Check integration status and install the embed into your codebase
- Verify the embed is live, check which user attributes it is actually sending (so it can tell whether `identify()` really landed, rather than asking you to open devtools), and whitelist your production domain

## Editing tours

Your agent can change a tour after it's built — no need to re-create it. The
typical flow:

1. `list_tours` — find the tour you mean.
2. `get_tour` — read its current settings and steps (each with its id).
3. Make changes with `update_tour_config` (name + behavior settings),
   `update_tour_visibility` (targeting / URL pattern / screen width / frequency /
   trigger — send the complete value, it replaces rather than merges),
   `update_tour_theme` (this tour's colors / typography / alignment / button
   radius / overlay / progress / highlight — merged), `update_step` (a step's
   content/behavior/appearance — keeps the step's id and its
   analytics), `add_step`, `delete_step`, and `reorder_steps`.

Edits land on the unpublished tour, just like creation — you still review and
publish from the dashboard.

## Theme & branding

StepsKit has **four project-wide default themes** — one each for tours, tooltips,
announcement banners, and survey cards — plus a **per-item override** on every
tour, tooltip, announcement, and survey. Your agent can read your brand colors
from your codebase (Tailwind theme tokens, CSS variables, design tokens) — or
just ask — and apply them, so StepsKit looks like your product without touching
the dashboard:

- `get_project_theme` — read all four defaults at once (each with the built-in
  values it resolves to).
- `update_project_theme` — set one default, chosen with `surface`: `"tours"` (the
  default), `"tooltips"`, `"announcements"`, or `"surveys"`. Setting one never
  disturbs the others.
- `update_tour_theme` — override a single tour where you want it to differ (a
  tooltip, announcement, or survey uses its own `theme` field the same way).

The keys differ by surface: tours and tooltips take the popover theme
(`bgColor`, `textColor`, `buttonColor`, `buttonTextColor`, plus typography —
`titleFontSize`, `bodyFontSize`, `titleAlign`, `bodyAlign` — and, for tours
only, overlay, progress, highlight border, `buttonsAlign`, and
`buttonRadius`), while announcements and
surveys take the flat banner/card theme (`backgroundColor`, `textColor`,
`buttonBackgroundColor`, `buttonTextColor`).

All theme writes merge (send only the keys you're changing), and `reset`
restores the inherited values. The cascade is built-in defaults → that surface's
project theme → the item's own theme.

## Tooltips

A **tooltip** is a single contextual indicator — a `?`/info glyph, a dot/pulse, or a
"NEW"/"BETA" text badge — anchored to one element that opens a small popover
(title, body, and an optional CTA button) on click. Unlike a tour, it's one
element and one popover, not a sequence. The flow mirrors tours:

1. `create_tooltip` — your agent infers the anchor selector and copy from your code
   and authors the tooltip in one call. It's created **unpublished**.
2. `list_tooltips` / `get_tooltip` — find and read a tooltip's full editable state.
3. `update_tooltip` — change its content, indicator, CTA, visibility (targeting /
   URL pattern / screen width / frequency — sent complete, replacing), or its
   per-tooltip theme (merged; `reset_theme` clears the override). `delete_tooltip`
   removes it (it asks you to confirm first).

Tooltips inherit the project's **tooltip** default theme — use
`update_project_theme` with `surface: "tooltips"` to brand them all, and a
tooltip's own `theme` only to make one differ. As with tours, you review and
publish tooltips from the dashboard.

## NPS surveys

A **survey** is a small bottom-corner slide-in card that asks a visitor the
classic NPS question — "how likely are you to recommend us?" — on a selectable
rating scale (NPS 0-10, a 1-5 numeric scale, or a five-emoji sentiment scale),
with an optional open-text follow-up and a thank-you. Unlike a tour or tooltip, it
_collects_ feedback rather than delivering it, and it isn't anchored to a page
element. The flow mirrors tours and tooltips:

1. `create_survey` — your agent writes the question/labels/follow-up copy to fit
   your product (or accepts sensible defaults) and authors the survey in one call.
   It's created **unpublished**.
2. `list_surveys` / `get_survey` — find and read a survey's full editable state.
3. `update_survey` — change its question, rating scale, scale labels, follow-up,
   thank-you, position, dismissible, re-survey window, visibility (targeting / URL
   pattern / screen width — sent complete, replacing), or its card theme (merged;
   `reset_theme` clears it back to the project's survey-card default).

As with tours and tooltips, you review and publish surveys from the dashboard.

## Announcements

An **announcement** is a slim banner strip pinned to the top or bottom of the
page (edge-to-edge or floating) — a title, a body, an optional CTA button, and an
optional lucide/emoji icon — for feature launches, maintenance notices, and
promos. It isn't anchored to a page element, and one banner shows at a time
(first match wins). The flow mirrors the other experiences:

1. `create_announcement` — your agent writes the copy (say, from the changelog or
   a just-merged feature branch) and authors the banner in one call. It's created
   **unpublished**.
2. `list_announcements` / `get_announcement` — find and read an announcement's
   full editable state.
3. `update_announcement` — change its content, CTA, icon, position and corner
   radii, schedule, visibility (targeting / URL pattern / screen width /
   frequency — sent complete, replacing), or its banner theme (merged;
   `reset_theme` clears it back to the project's announcement default).
   `delete_announcement` removes it (it asks you to confirm first).

Announcements can be **scheduled**: set `start_at` / `end_at` (ISO timestamps)
and the banner only runs inside that window, enforced server-side — so "announce
the launch Monday 9am, take it down Friday" works without a calendar reminder.

As with everything else, you review and publish announcements from the dashboard.

## Not supported yet

These are on the roadmap, not available today — the agent should tell you so
rather than invent a workaround:

- Per-step visual styling (per-step color overrides — per-tour and project-wide themes are supported)
- Per-step and per-tooltip media/images (uploading requires the dashboard)
- Read analytics
- Custom event tracking — `window.stepskit.track()` exists in the SDK's method
  list but is a no-op today: it warns once and discards the call. Your agent is
  told not to wire product events to it, since those calls would be dead code.
  Targeting runs off the user attributes you pass to
  [`identify`](/docs/concepts/user-attributes.md), not off tracked events.

## Excluded by design

- **Publishing a tour** — always a deliberate action in the dashboard, so nothing
  the agent writes goes live without your review.
- **Creating your account or a new project** — projects are made in the
  dashboard, and a token has to be minted there first. Moving between projects
  you already own is supported (`list_projects` / `select_project`); creating
  one isn't.

## Try asking

- "Set up StepsKit in this project and build a 3-step onboarding tour for the dashboard. Install the embed if it isn't already, then infer the target selectors from the code."
- "Create a welcome tour: a modal intro, then callouts pointing at the New Project button and the search bar."
- "We just shipped a new feature — build a short tour that points existing users to it, and only show it on the page where the feature lives."
- "Open my Welcome tour and tighten the copy on every step, then rename the Next button to 'Continue'."
- "Only show my Welcome tour to visitors on the Pro plan, and only on the /dashboard page."
- "Match StepsKit to our brand — pull the colors from our Tailwind config and set the project defaults for tours, tooltips, banners, and surveys."
- "Add a final 'You're all set' modal step to the onboarding tour and move it to the end."
- "Add a 'NEW' badge tooltip next to the Analytics nav item that opens a popover explaining the feature, with a button that starts the analytics tour."
- "We ship the new reporting feature next Monday — create a top banner announcing it with a 'See what's new' link to the changelog, scheduled to run Monday through Friday."
- "Which StepsKit projects can you see? Switch to the one for this app before you create anything."
- "What can the StepsKit MCP do right now? Can you publish a tour or set its theme?"