Troubleshooting

The server doesn't appear after setup

  • Restart the agent. MCP servers load at startup — Claude Code, Cursor, and Codex all need a restart (or reload) after you add the config.
  • Wrong config key or format. Cursor/Claude use mcpServers; VS Code/Copilot uses servers; Codex uses TOML, not JSON. A mismatch is ignored silently. See Connect your agent.
  • Run the command yourself. Copy the command + args from your config and run npx -y @stepskit/mcp in a terminal — any error (network, Node version) prints directly instead of being swallowed by the client.

"STEPSKIT_TOKEN is not set" or 401 errors

  • Make sure STEPSKIT_TOKEN is in the server's env and is a full sk_live_… token.
  • A 401 means the token is invalid or revoked. Generate a fresh one in the dashboard (AI Agents → Generate token) and update your config — tokens are shown only once.

A tour was created but doesn't show up on my site

A created tour is an unpublished draft and only renders when:

  1. The embed is installed and live. Ask the agent to run verify_integration, or check the dashboard. If it's not live, load any page of your running app once so the embed pings StepsKit.
  2. The domain is allowed. Production domains must be whitelisted (add_allowed_domain); localhost is always allowed.
  3. You published it. The agent never publishes — review and publish the tour from the StepsKit dashboard.

Steps point at the wrong element

When the agent infers a selector from source and isn't sure it matches the live DOM, it marks the step selector_confidence: "low" — these show a "Review selector" badge in the canvas. Open the tour, confirm or fix the target, and clear the badge. Prefer stable selectors (data-testid, id) in your markup to make this rare.

The agent claims it can do something it can't

The agent can edit an existing tour — its name, behavior settings, visibility (targeting / URL pattern / screen width / frequency / trigger), and steps. What it cannot do via MCP is set a tour's theme/colors, upload media/images, publish a tour, create hints or announcements, or read analytics. If it offers one of those, point it at get_capabilities (or see Capabilities & limits) — those aren't supported via MCP yet.