Connect your coding agent

Before you start

• A Steppr workspace on any plan. The 7-day trial works, and so does Starter.
• The owner or admin role in that workspace. Editors and viewers cannot create API keys.
• A coding agent that supports MCP servers over HTTP, such as Claude Code or Cursor, opened in the repository of the app you want to build tours for.
• The Steppr snippet installed on your site with at least one allowed origin that is a full origin and not a wildcard pattern. This is only needed for preview links. Without it the agent can still create drafts, and you review them from the dashboard.

Create an API key

1. In the dashboard, open Settings, then API keys.
2. Choose a name that says where the key will be used, for example the developer or tool.
3. Choose the access level. Read & write can create and edit drafts. Read only can list and read tours and checklists and nothing else.
4. Copy the key. It starts with stp_api_ and is shown once. Steppr stores a SHA-256 hash of it, so it cannot be shown again. If you lose it, revoke it and create a new one.

A workspace can have up to 20 active keys. Issuing one key per developer or per tool lets you revoke a single key without interrupting anyone else.

Connect your agent

The server speaks MCP over Streamable HTTP at https://api.steppr.io/mcp and authenticates with the key in an Authorization header. Replace stp_api_YOUR_KEY in the snippets below with your key. The API keys page in the dashboard shows the same snippets with a new key already filled in.

Claude Code

Run this from your project directory:

claude mcp add --transport http steppr https://api.steppr.io/mcp \
  --header "Authorization: Bearer stp_api_YOUR_KEY"

By default Claude Code saves the server in its local scope, which is private to you and applies to the current project. Add --scope user to make it available in all of your projects. Avoid --scope project: it writes the server, including the key, to a .mcp.json file in the repository.

Cursor

Add a steppr entry to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json to make it available in every project:

{
  "mcpServers": {
    "steppr": {
      "url": "https://api.steppr.io/mcp",
      "headers": {
        "Authorization": "Bearer stp_api_YOUR_KEY"
      }
    }
  }
}

Other MCP clients

Any client that supports remote MCP servers over Streamable HTTP with a custom request header can connect. It needs these three values:

URL:        https://api.steppr.io/mcp
Transport:  Streamable HTTP
Header:     Authorization: Bearer stp_api_YOUR_KEY

Check the connection

In Claude Code, claude mcp list shows whether the server connected. In any agent, ask it to call the get_workspace tool. The result names the workspace the key belongs to, the key's access level, the plan and the plan limits that apply to authoring.

Example prompt

Describe the flow the way you would brief a colleague: which page, which elements, in what order, and where in the repository the relevant components are.

Use the steppr MCP server to draft a product tour called "Create your first project".

It should run on the /projects page: point at the New project button and advance
when the user clicks it, then point at the project name field and wait until it
has a value, then finish with a short modal.

Read the components under src/features/projects to find the selectors. Prefer
data-testid attributes. If an element has no stable hook, tell me before adding one.

What the agent does with it

The exact sequence is up to the agent, but the tool descriptions and the authoring guide steer it towards this:

1. It calls get_authoring_guide. The guide is a Markdown reference covering step types, selector rules, the recognised config keys, copy limits, targeting and trigger shapes, and error codes.
2. It calls get_workspace to confirm the key can write and to read the plan limits, and usually list_tours to avoid duplicating an existing flow.
3. It reads your components and picks a selector for each anchored step, in the same priority order as the click-to-build picker: a data-testid attribute first, then a stable id, then a short chain of stable classes. The guide tells it not to guess, and to propose adding a data-testid when an element has no stable hook.
4. It calls create_tour_draft once, with the name, every step, the targeting rules and the triggers. Steppr validates the input and writes the tour and its steps in a single transaction, so a failed call leaves nothing half-built.
5. It reports back with what it built and the review links from the tool result.

For the prompt above, the arguments to create_tour_draft look like this:

{
  "name": "Create your first project",
  "steps": [
    {
      "type": "tooltip",
      "selector": "[data-testid=\"new-project-button\"]",
      "title": "Start a project",
      "body": "Projects hold your boards and files. Click **New project** to create one.",
      "config": {
        "advanceOn": "anchor-click"
      }
    },
    {
      "type": "tooltip",
      "selector": "[data-testid=\"project-name-input\"]",
      "title": "Name it",
      "body": "Give the project a name. You can rename it later.",
      "config": {
        "requireToAdvance": {
          "type": "anchor_has_value"
        }
      }
    },
    {
      "type": "modal",
      "title": "Project created",
      "body": "Invite a teammate from the **Team** page when you are ready."
    }
  ],
  "targeting": [
    {
      "type": "url_match",
      "pattern": "/projects",
      "match": "contains"
    }
  ],
  "triggers": [
    {
      "type": "page_load"
    }
  ]
}

The result is the full tour object, the same shape as the REST API's tour, with status set to draft and a links object. It is preceded by a sentence telling the agent that the tour is not live and that only a person can publish it.

Review and publish

Agents make mistakes with selectors. An element may only render for some users, a list may contain several matches, or the agent may have added a data-testid that is not deployed to the site you are previewing. Reviewing the draft is part of the workflow, and it is the reason the API has no publish operation.

Every tool that returns a tour includes two links:

• links.previewUrl opens your own site with the draft rendered by the snippet. Targeting and triggers are ignored in preview so the tour starts straight away. The link opens the site root, so navigate to the page the tour is for. It carries a signed token that expires after 24 hours, and any later call that returns the tour includes a fresh link. It is null when the workspace has no usable allowed origin, when the key is read only, or when the subscription is not active.
• links.dashboardUrl opens the tour in the dashboard editor. It does not expire. Checklists only have this link.

Step through the tour in the preview. When a selector does not match, the snippet waits up to three seconds for the element to appear and then shows that step as a centred card. A tooltip that appears in the middle of the page instead of next to its element is the sign of a missed selector. To fix one, open the tour from the dashboard link, start the builder on your site and click the correct element. The picker generates the selector for you. You can also ask the agent to correct it with update_step.

When the draft is right, publish it from the dashboard. If the agent edits a tour that is already published, the change is saved to the draft only. Your users continue to see the published version, and the tour reports hasUnpublishedChanges: true until someone republishes.

Tool reference

Tools that write require a Read & write key and an active subscription or trial. Every tool that changes a tour returns the full updated tour, including current step ids and order.

Field-level shapes for steps, targeting rules, triggers and checklist items are in the API reference. The MCP tools and the REST endpoints validate with the same schemas.

Permissions and security

• A key belongs to one workspace. There is no workspace parameter on any tool, so a key cannot reach another workspace.
• Keys are accepted only by the MCP server and the /api/v1 authoring API. The rest of the Steppr API rejects them, so a key cannot read or change billing, team members or other API keys.
• A key's access is Read & write or Read only. It can never have admin or owner rights, whoever created it.
• No tool publishes, archives or deletes a tour or checklist, and none can change a flow's status.
• The full key is shown once. Steppr stores a SHA-256 hash and a short display prefix so you can tell keys apart in the list.
• Revoking a key from the API keys page takes effect on the next request. The page also shows when each key was last used.
• Writes need an active subscription or trial. When a trial ends or a subscription lapses, keys can still read but every write returns SUBSCRIPTION_INACTIVE.
• Requests are rate limited to 120 per minute per IP address.

Treat a key like any other secret. Keep it out of the repository, out of shared agent configuration files and out of CI logs.

What is not supported

• Publishing, archiving or any other change of status. These happen in the dashboard.
• Deleting tours or checklists. An agent can delete individual steps only.
• Editing a checklist after it has been created.
• Announcements. They are created in the dashboard.
• Theme presets and tour chaining. Drafts use the workspace default theme until you change it in the editor.
• Elements inside a Shadow DOM or a cross-origin iframe on your site. The snippet cannot target them, so the agent is told to choose a nearby element or use a modal step.

Troubleshooting

If something here does not match what you see, email hello@steppr.io with the error code and the tool name.