# @stepskit/mcp — MCP server reference

> Reference for the @stepskit/mcp npm package: configuration, environment variables, project selection, every tool (setup, tours, steps, tooltips, surveys, announcements, theme), guardrails, and token security.

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

[`@stepskit/mcp`](https://www.npmjs.com/package/@stepskit/mcp) is the StepsKit
[MCP](https://modelcontextprotocol.io) 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 StepsKit access token — either
pinned to one project or scoped to your whole account. 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](/docs/ai-agents/connect.md); for what you can and can't ask it
to do, see [Capabilities & limits](/docs/ai-agents/capabilities.md).

## Running it

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

```bash
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):

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

If that file is going into git, use the form that references the token instead
of holding it — the mechanism is per-client, so copy yours from
[Connect your agent](/docs/ai-agents/connect.md#keep-the-token-out-of-the-config-file).

## Environment variables

| Variable | Required | Description |
| --- | --- | --- |
| `STEPSKIT_TOKEN` | Yes | Access token (`sk_live_...`). Mint a project-scoped one on a project's **AI** page, or an account-scoped one under **Account settings**, in the [dashboard](https://stepskit.com/app). |
| `STEPSKIT_PROJECT` | No | Default project for an **account-scoped** token — a project slug or id. Ignored by a project-scoped token, which is pinned by the credential. |
| `STEPSKIT_API_URL` | No | API base URL. Defaults to `https://stepskit.com`. |

`--project <slug-or-id>` in the server's `args` does the same job as
`STEPSKIT_PROJECT` and outranks it. Prefer the arg if you export environment
variables globally: an exported variable follows you into every repo, while an
arg belongs to one server entry. Full precedence rules are on
[Connect your agent](/docs/ai-agents/connect.md#pick-a-project).

## Tools

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.

### Projects

| Tool | What it does |
| --- | --- |
| `list_projects` | Lists the projects the token can reach, marks the selected one, and reports whether the token is pinned to a project or spans the account. |
| `select_project` | Switches which project subsequent calls act on, for the rest of the session. Takes a slug or id; refuses on a project-scoped token, which can't switch. |

Most project-level tools also take an optional `project` argument (slug or id)
that overrides the selection for that one call: `get_integration_status`,
`verify_integration`, `add_allowed_domain`, `get_project_theme`,
`update_project_theme`, `create_tour`, `list_tours`, `list_tooltips`,
`list_surveys`, and `list_announcements`.

### 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's tours 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 themes

| Tool | What it does |
| --- | --- |
| `get_project_theme` | Reads all four project-wide default themes — tours, tooltips, announcement banners, and survey cards — raw and resolved. |
| `update_project_theme` | Sets ONE project-wide default, picked with `surface` (`tours` — the default — `tooltips`, `announcements`, or `surveys`). Merged; `reset` restores that surface's built-in 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

A token is a long-lived credential, in one of two scopes:

- **Project-scoped** — minted on a project's **AI** page and pinned to that
  project. The smallest blast radius if it leaks.
- **Account-scoped** — minted under **Account settings**, and able to reach every
  project you own. One token per machine instead of one per repo; the tradeoff is
  that a leak exposes all of them.

Either way:

- Keep the literal token out of committed files. The dashboard emits config that
  **references** the token instead of containing it — `${STEPSKIT_TOKEN}` for
  Claude Code and Claude Desktop, an `inputs` prompt for VS Code, `env_vars` for
  Codex — so the config file is safe to commit. The mechanisms aren't
  interchangeable and the wrong one fails silently, so copy the form for your
  client from
  [Connect your agent](/docs/ai-agents/connect.md#keep-the-token-out-of-the-config-file).
  Where a client documents no such mechanism (Cursor), gitignore the file
  instead.
- 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: project tokens from that project's **AI** page,
  account tokens from **Account settings**, which lists every token you own and
  its scope. A revoked token stops working immediately.

## Source & issues

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