@stepskit/mcp

@stepskit/mcp

The StepsKit MCP server — install StepsKit and author product onboarding tours from your codebase through your AI coding agent (Claude Code, Cursor, any MCP client).

Because the MCP runs inside your agent — which has your codebase on disk — it can do the whole setup for you. Ask your agent to "set up StepsKit in this project and build an onboarding tour" and it will:

1. Check whether the embed is installed (get_integration_status).
2. Detect your framework and add the embed snippet to the right file.
3. Verify the embed is live once you load a page (verify_integration).
4. Whitelist your production domain (add_allowed_domain).
5. Author the tour (create_tour) — created unpublished, so you review and publish it from the StepsKit dashboard.

Already have tours? Ask your agent to "edit my onboarding tour" and it will list_tours → get_tour → change copy, buttons, settings, steps, or visibility in place (update_tour_config, update_tour_visibility, update_step, add_step, delete_step, reorder_steps).

It can also author tooltips — single contextual indicators (a ?/info glyph, a dot/pulse, or a "NEW"/"BETA" badge) anchored to one element that open a small popover on click. Ask it to "add a tooltip next to the Settings button" and it will create_tooltip (unpublished, like tours), or edit existing ones with list_tooltips → get_tooltip → update_tooltip / delete_tooltip.

Prerequisites

You need a StepsKit project and an MCP access token for it (sk_live_...). The agent handles installing the embed for you — you don't need to paste any snippet into your site by hand.

Setup

Mint a token (from the repo, until the dashboard UI ships):

pnpm --filter @stepskit/web mcp:token <your-project-slug>

Add the server to your MCP client config:

{
  "mcpServers": {
    "stepskit": {
      "command": "npx",
      "args": ["-y", "@stepskit/mcp"],
      "env": {
        "STEPSKIT_TOKEN": "sk_live_...",
        "STEPSKIT_API_URL": "https://stepskit.com"
      }
    }
  }
}

STEPSKIT_API_URL is optional (defaults to https://stepskit.com). Set it to http://localhost:3000 for local development.

Tools

Tool	Purpose
get_integration_status	Read onboarding state (embed installed?, domains, tour count) + the ready-to-paste install snippet. Call first.
verify_integration	Confirm the embed has pinged StepsKit (is live) after install.
add_allowed_domain	Whitelist a production domain so tours play there (localhost is always allowed).
suggest_url_pattern	Turn a concrete URL into a url_pattern for a dynamic route — wildcards generated-ID segments (/items/abc123/edit → /items/*/edit). There's no [id] placeholder syntax.
list_tours	List this project's tours (id, name, slug, step count, published state).
get_tour	Read one tour's full editable state — settings, visibility, + ordered steps with ids and overrides. Call before editing.
create_tour	Author an unpublished tour from codebase context.
update_tour_config	Rename a tour and/or change its behavior settings (buttons, labels, progress, keyboard, overlay-click, padding, auto-navigate). Settings merge.
update_tour_visibility	Set who sees the tour and when — audience targeting rules, page URL pattern, min screen width, show-once frequency, trigger (page_load/manual). Fields replace, not merge.
update_step	Edit a step's content + behavior. Keeps the step id (and its analytics). Overrides merge.
add_step	Append a new step to a tour.
delete_step	Delete a step. Destructive (orphans the step's analytics) — requires confirm: true.
reorder_steps	Set the order of a tour's steps (pass the complete set of step ids).
get_project_theme	Read the global theme every tour and tooltip inherits.
update_project_theme	Set the global theme (all tours/tooltips inherit it) or reset it. Merges.
update_tour_theme	Override one tour's theme (or reset to inherit the project theme). Merges.
list_tooltips	List this project's tooltips (id, name, slug, published state, anchored?).
get_tooltip	Read one tooltip's full editable state — content, indicator, CTA, visibility, theme. Call before editing.
create_tooltip	Author an unpublished tooltip from codebase context (anchor + content + indicator + placement + CTA + visibility + optional theme).
update_tooltip	Edit a tooltip's content/indicator/CTA, name, visibility (replace), and theme (merge; reset_theme clears).
delete_tooltip	Delete a tooltip. Destructive (orphans its analytics) — requires confirm: true.

create_tour

Input	Type	Notes
name	string	Tour name
steps[]	array	Ordered steps (min 1)
steps[].type	callout | modal	callout anchors to an element; modal is centered
steps[].title	string?	Step heading
steps[].content	string?	Step body
steps[].target_selector	string?	Required for callout. Prefer stable selectors
steps[].position	top|bottom|left|right?	Callout placement
steps[].selector_confidence	high | low?	low flags the step for review in the dashboard

Editing an existing tour

list_tours → get_tour (to read step ids + current settings) → then edit:

Tool	Key inputs
update_tour_config	tour_id, name?, settings? (TourSettings behavior subset — buttons, button labels, showProgress, allowClose, overlayClickBehavior, allowKeyboardControl, animate, smoothScroll, disableActiveInteraction, stagePadding/stageRadius/popoverOffset, autoNavigateOnNext)
update_tour_visibility	tour_id + any of targeting (audience everyone|filtered, rules[], logic AND|OR), url_pattern, min_screen_width (or null), frequency ({type:'show_once',per:'visitor'} or null), trigger ({type:'page_load'|'manual'}). Send the complete value per field — they replace, not merge.
update_step	step_id + any of type, title, content, target_selector, position, backdrop, spotlight_padding, url_pattern, overrides (per-step button labels/visibility, showProgress, align, disableActiveInteraction)
add_step	tour_id, type (+ same step fields as update_step)
delete_step	step_id, confirm: true
reorder_steps	tour_id, step_ids[] (the complete set, in the new order)

create_tooltip

A tooltip is a flat, single record (one element, one popover) — not a sequence. create_tooltip takes name plus any of:

Input	Type	Notes
target_selector	string?	Element the tooltip anchors to. Without it the tooltip is a draft and won't render until anchored
title, content	string?	Popover heading + body
icon_type	question|info|dot|pulse|badge?	Indicator style. badge needs icon_label
icon_label	string?	Badge text (e.g. NEW). Required for badge
icon_color, icon_bg_color, icon_size	string?/number?	Indicator color + size (8–96px)
placement	top|right|bottom|left|auto?	Popover side. offset_x/offset_y nudge it
cta_label + cta_action	string? + link|start_tour|custom?	Optional CTA. Target is cta_url / cta_tour_id / cta_event_key
cta_align, cta_variant, cta_size, cta_bg_color, cta_text_color	enums/strings?	CTA button styling
dismissible	boolean?	Whether the visitor can dismiss it
targeting, url_pattern, min_screen_width, frequency	—	Visibility (same shapes as a tour; tooltips have no trigger)
theme	object?	Per-tooltip popover theme override (else inherits the project theme)

Editing an existing tooltip

list_tooltips → get_tooltip → then edit:

Tool	Key inputs
update_tooltip	tooltip_id + any of name, the content/indicator/CTA fields above, the visibility fields (replace — send the complete value), theme (merged), or reset_theme: true
delete_tooltip	tooltip_id, confirm: true

The agent composes the plan; this server validates it and persists it. It never publishes tours or tooltips, and it cannot upload per-step or per-tooltip media or create announcements — those stay deliberate actions in the dashboard.

Security

The token is a long-lived, per-project credential. Keep it out of committed files (use the MCP client's env config, not a checked-in JSON). Tokens are prefixed sk_live_ so secret-scanners recognize a leak. Revoke a leaked token by clearing its row in mcp_access_tokens.

Learn more

• StepsKit — stepskit.com
• Build tours with your AI coding agent — stepskit.com/features/ai-agents
• Dashboard — stepskit.com/app