MCP server reference

@stepskit/mcp is the StepsKit MCP server, published on npm. It runs locally inside your MCP client (Claude Code, Cursor, Codex, Claude Desktop, VS Code, and others) and talks to the StepsKit API with a per-project access token. Through it, your agent can install the embed and author tours, tooltips, NPS surveys, and announcements from your codebase.

This page documents the package itself. For per-client setup steps, see Connect your agent; for what you can and can't ask it to do, see Capabilities & limits.

Running it

The server is always started the same way, regardless of client:

npx -y @stepskit/mcp

Your MCP client launches this command and communicates over stdio — you never run it by hand. A minimal config (the mcpServers JSON shape most clients use):

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

Environment variables

Variable	Required	Description
`STEPSKIT_TOKEN`	Yes	Per-project access token (`sk_live_...`), minted on your project's AI page in the dashboard.
`STEPSKIT_API_URL`	No	API base URL. Defaults to `https://stepskit.com`.

Tools

31 tools across seven groups. Every tool carries a full JSON schema, and get_capabilities returns the authoritative can/can't list — so your agent always knows the current surface without relying on docs.

Setup & integration

Tool	What it does
`get_integration_status`	Call first — returns onboarding state (embed installed?, allowed domains, tour count) plus a ready-to-paste install snippet.
`verify_integration`	Confirms the embed has actually pinged StepsKit after install.
`add_allowed_domain`	Whitelists a production domain so experiences play there (localhost is always allowed).
`suggest_url_pattern`	Turns a concrete URL into a wildcard `url_pattern` for dynamic routes (`/items/123/edit` → `/items/*/edit`).
`get_capabilities`	Lists what the MCP can and can't do right now.

Tours

Tool	What it does
`create_tour`	Authors a complete tour (settings, visibility, theme, ordered steps) in one call — always as an unpublished draft.
`list_tours`	Lists the project's tours.
`get_tour`	Reads one tour's full editable state — settings, visibility, theme, and steps with ids.
`update_tour_config`	Renames a tour and edits behavior settings (buttons, labels, progress, keyboard, overlay-click, completion redirect).
`update_tour_visibility`	Sets targeting, page URL pattern, minimum screen width, show-once frequency, and trigger. Sent complete — replaces, not merges.
`update_tour_theme`	Overrides one tour's theme (colors / overlay / progress / highlight). Merged; the rest inherits the project theme.

Steps

Tool	What it does
`add_step`	Adds a callout (anchored to a CSS selector) or modal step.
`update_step`	Edits a step's content and behavior. Keeps the step id and its analytics — prefer over delete + add.
`delete_step`	Removes a step. Destructive — requires `confirm: true`.
`reorder_steps`	Reorders a tour's steps.

Tooltips

Tool	What it does
`create_tooltip`	Creates an unpublished tooltip — anchor selector, indicator style (`?`/info glyph, dot/pulse, or NEW/BETA badge), popover content, open trigger, optional CTA.
`list_tooltips` / `get_tooltip`	Find and read a tooltip's full editable state.
`update_tooltip`	Edits content, indicator, CTA, visibility, or per-tooltip theme.
`delete_tooltip`	Removes a tooltip. Destructive — requires `confirm: true`.

NPS surveys

Tool	What it does
`create_survey`	Creates an unpublished bottom-corner NPS survey — question, rating scale (0–10, 1–5, or emoji), follow-up, thank-you, re-survey window.
`list_surveys` / `get_survey`	Find and read a survey's full editable state.
`update_survey`	Edits question, scale, labels, position, visibility, or card theme.

Announcements

Tool	What it does
`create_announcement`	Creates an unpublished top/bottom banner — title, body, optional CTA and icon, optional schedule window (`start_at` / `end_at`).
`list_announcements` / `get_announcement`	Find and read an announcement's full editable state.
`update_announcement`	Edits content, CTA, icon, position, schedule, visibility, or banner theme.
`delete_announcement`	Removes an announcement. Destructive — requires `confirm: true`.

Project theme

Tool	What it does
`get_project_theme`	Reads the global theme every tour and tooltip inherits.
`update_project_theme`	Sets the global theme — brand colors, overlay, progress, highlight. Merged; `reset` restores defaults.

Guardrails

The agent composes the plan; the server validates it and persists it. By design:

It never publishes. Everything it creates arrives unpublished — publishing is a deliberate human action in the dashboard.
Destructive operations require confirm: true — delete_step, delete_tooltip, and delete_announcement refuse to run without it.
No media uploads and no analytics reads — those stay in the dashboard.

Token security

The token is a long-lived, per-project credential:

Keep it out of committed files — use your MCP client's env config, not a checked-in JSON. For project-scoped config files (like .mcp.json), make sure the file is gitignored or use an env-var reference if your client supports it.
Tokens are prefixed sk_live_ so secret scanners recognize a leak.
Tokens are stored hashed — they're shown once at mint time and can't be recovered, only replaced.
Revoke a token any time from the dashboard's AI page; a revoked token stops working immediately.

Source & issues

The package source lives at github.com/nikitabobers/stepskit-mcp (MIT licensed) and is synced from the StepsKit monorepo on every release. Issues and bug reports are welcome there.