Use StepTrail from an AI assistant

StepTrail can act as a connector for AI assistants that support the Model Context Protocol (MCP), such as Claude Code and Claude Desktop. You describe what you want in plain words and the assistant uses StepTrail's tools to look up what StepTrail already knows about your system and build a test.

The assistant does the language understanding. StepTrail answers from its screen memory and does the precise work, so there is nothing extra to pay for.

What works today

• Local assistants that start a program on your computer (Claude Code, Claude Desktop and other MCP clients). This is what is built.
• ChatGPT can only connect to a server on the internet, so it needs a remote version of this connector. That is planned, not built. See What's coming.
• The tools look up, plan, write files and, if you switch it on, run a replay in a browser. Running a replay is off by default: see Let the assistant run a test.

Connect it

You need StepTrail installed and some screen memory (replay a recording with --memory shop first, see Screen memory).

Claude Code. Open a terminal in your project folder and run (change the path to where you installed StepTrail, and the address to your own test site):

claude mcp add steptrail -e STEPTRAIL_BASE_URL=https://staging.example.com -- node /path/to/steptrails/bin/mcp.js

Other assistants (Claude Desktop and any app that reads an mcpServers list in its settings):

{
  "mcpServers": {
    "steptrail": {
      "command": "node",
      "args": ["/path/to/steptrails/bin/mcp.js"],
      "env": {
        "STEPTRAIL_PROJECT_DIR": "/path/to/your/project",
        "STEPTRAIL_BASE_URL": "https://staging.example.com"
      }
    }
  }
}

Keep the name (steptrail) before the -e setting in the Claude Code command: some versions of Claude Code read a setting placed before the name as part of the name. If your version still has trouble, use the JSON form above or Claude Code's claude mcp add-json command. Each assistant's own documentation has the exact place to put this; the setup screens change over time.

Settings

These are set when you add the server, not by the assistant.

Setting	What it is for
STEPTRAIL_PROJECT_DIR	The folder the assistant may read and write in. Default: the folder the server was started in
STEPTRAIL_BASE_URL	The address tests are built for, for example your staging site. Needed by build_recording. The assistant cannot choose or change it
STEPTRAIL_ALLOWED_BASES	Optional. A comma-separated list of addresses that are allowed; anything else is refused
STEPTRAIL_MEMORY_DIR	Where the memory is kept, relative to the project folder. Default: .steptrail

What the assistant can do

Tool	What it does	Changes files?
list_systems	Lists the systems automated so far, with screens, scenarios and the last result	No
show_memory	Shows the screens, elements, best locators and routes StepTrail remembers	No
find_route	Finds the known route between two screens, for example /login to /orders	No
find_element	Finds elements by name, with their ranked locators and how often each passed	No
check_privacy	Scans the memory for personal data and addresses	No
summarise_report	Summarises a replay report: the failing step, the worst security findings with fixes, the slowest pages	No
build_recording	Builds a recording from structured steps, filling in the known route	Writes a new .json file
generate_playwright	Makes the Playwright test from a recording	Optionally writes a .spec.js file
run_replay	Runs a recording in a browser and summarises the result (off by default)	Can save a report file; performs the recorded actions on the real site

Let the assistant run a test

run_replay replays a recording in a real browser, which performs the recorded clicks and typing on the real site. It can submit forms, so you must switch it on yourself and say where it may run. Add two settings to the connector:

Setting	What it is for
STEPTRAIL_ALLOW_REPLAY=true	Turns the tool on. Without it the assistant does not even see it
STEPTRAIL_ALLOWED_BASES	The addresses a replay may use, comma-separated, for example https://staging.example.com. Required
STEPTRAIL_SECRETS, STEPTRAIL_FILES	Passwords and upload paths, set here by you, never typed into the chat. See Settings
STEPTRAIL_REPLAY_TIMEOUT_SECONDS	Optional time limit, default 180 seconds (from 1 to 600)

How it behaves:

1. Preview first. Without confirm it only describes what it would do: the number of steps, the kinds of action, and whether the settings it needs are set. The assistant is told to explain this and ask you before going on.
2. Only allowed addresses. A recording that uses any address outside your list is refused, and the refusal does not repeat the address.
3. Passwords stay with you. If a login needs a password you have not set, nothing runs and the assistant is told not to ask you for it in the chat.
4. Limits. One replay at a time, at most 200 steps, 1 to 3 repeats, and the time limit above; when it is reached the replay and its browser are stopped.
5. A summary comes back: passed or failed, the failing step, how many steps healed, security findings with how to fix them, and the slowest pages, with addresses shown as {base} patterns and no screenshots. A full report can be saved in the project folder.
6. Memory. Give a system name and the replay also uses and updates the screen memory; a new name starts a new memory.

Your assistant should also ask you before calling it, because the tool is marked as one that changes things outside your computer. Treat the allowed list as the real safety line and only list sites you are allowed to test.

Try it

Ask the assistant something like:

Using StepTrail, what systems do we have? For the shop, show me the route from the login page to the orders page, then build a test that logs in as a user and opens an order.

The assistant looks up the screens, plans the steps, and calls build_recording. If something is not known, for example an element that was never recorded, nothing is written and the assistant gets a list of what is missing, so it can ask you instead of guessing.

Built-in safety

• Files stay in the project folder. Paths outside it, including through links, are refused. Existing files are not overwritten unless you agree.
• The address is yours. The address a test is built for comes from your setting. The assistant has no argument to change it.
• Passwords never pass through the assistant. A password field is stored as a placeholder; you supply the real value with STEPTRAIL_SECRETS when the test runs.
• Personal data stays out. The assistant only sees what the screen memory holds (no typed values, hosts or personal text). Report addresses are shown as {base} patterns.
• Website text is labelled as data. Element names, titles and messages come from websites, so every answer tells the assistant to treat them as data and not instructions.
• Your assistant asks first. Tools that change files are marked as such, so assistants that confirm before acting will ask.

Limits

• It only knows what the screen memory holds, so replay your recordings with --memory first.
• A screen whose address contains an id (such as /orders/123) cannot be opened directly; a test starts from a screen without one and follows the known route.
• No remote server (so no ChatGPT connection) yet.