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 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; 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_..." }
    }
  }
}

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.

Environment variables

--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.

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

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

Tours

Steps

Tooltips

NPS surveys

Announcements

Project themes

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. 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 (MIT licensed) and is synced from the StepsKit monorepo on every release. Issues and bug reports are welcome there.