Connect your agent

The MCP server is identical for every client — it's always npx -y @stepskit/mcp with your STEPSKIT_TOKEN. What differs is only where the config lives and its format. The cleanest path is each tool's own mcp add command or UI, which writes the right file for you.

Get a token

Open your project in the StepsKit dashboard → AI Agents → Generate token. Copy it once (it's stored hashed and can't be shown again), then use it in the config below in place of sk_live_....

At a glance

After adding the server, restart your agent so it loads, then ask it to set up StepsKit and build a tour.

Claude Code

Run this in your project — it writes the config for you:

claude mcp add stepskit --env STEPSKIT_TOKEN=sk_live_... -- npx -y @stepskit/mcp

Or add it by hand to .mcp.json in your project root (use --scope user with the CLI, or your user config, to share it across projects):

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

Verify: run /mcp in Claude Code — stepskit should be listed and connected.

Cursor

Add it from Settings → Tools & MCP → New MCP Server, or create .cursor/mcp.json (project) / ~/.cursor/mcp.json (global):

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

Verify: open Settings → Tools & MCP — stepskit should show a green/active indicator and its tools listed.

Codex CLI

Run this — it writes Codex's config for you:

codex mcp add stepskit --env STEPSKIT_TOKEN=sk_live_... -- npx -y @stepskit/mcp

Or add it by hand to ~/.codex/config.toml:

[mcp_servers.stepskit]
command = "npx"
args = ["-y", "@stepskit/mcp"]

[mcp_servers.stepskit.env]
STEPSKIT_TOKEN = "sk_live_..."

Verify: run codex mcp list — stepskit should appear.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

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

Restart Claude Desktop — stepskit appears under the tools (🔌) menu.

VS Code / GitHub Copilot

Create .vscode/mcp.json:

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

Any other MCP client

Anything that speaks the Model Context Protocol works. Most clients (Windsurf, Zed, etc.) use the same mcpServers JSON shown above — just point them at npx -y @stepskit/mcp with STEPSKIT_TOKEN in the env.

Optional: add StepsKit rules to your agent

Drop this into your project's CLAUDE.md, .cursorrules, or AGENTS.md so your agent follows StepsKit conventions (stable selectors, unpublished-by-default, the current capability boundary) even outside an MCP call:

# StepsKit (product onboarding tours)

When this project involves StepsKit:

- Author tours through the StepsKit MCP server (`@stepskit/mcp`) — use its
  tools, don't hand-write API calls.
- Call `get_integration_status` before creating a tour. If the embed isn't
  installed, install it and run `verify_integration` (after the user loads a
  page) before creating tours.
- For tooltip steps, prefer stable selectors: `data-testid`, `id`, or a unique
  semantic class. Avoid brittle nth-child chains. Set
  `selector_confidence: "low"` when you infer a selector from source and aren't
  sure it matches the live DOM — low-confidence steps get flagged for review.
- Tours are created UNPUBLISHED. Never claim a tour is live; the user reviews and
  publishes it from the StepsKit dashboard.
- Before promising a capability, call `get_capabilities`. StepsKit MCP can
  CREATE tours (tooltip/modal steps) but cannot yet edit existing tours, set
  theme/targeting/frequency, add per-step media or styling, create
  hints/announcements, publish, or read analytics. Say so plainly instead of
  inventing a workaround.