Getting started

Overview

The Step MCP Server lets AI assistants and coding agents (such as Claude Code, Claude Desktop, and Cursor) drive the Step automation platform through the Model Context Protocol (MCP). It brings AI-powered software testing into your existing automation workflows: agents can author, run, and analyse test executions on Step without leaving their environment. Instead of clicking through the UI, you can triage a failed run (even a load test with thousands of failures) by asking in plain language and getting a cited root-cause summary back.

It is part of the broader Step AI ecosystem, alongside the Step AI Agent.

It is designed around three main capabilities:

• Authoring: Create a deployable Step Automation Package that can be executed on Step.
• Execution: Deploy and run automation packages on a Step instance.
• Analysis: Retrieve execution results and evidence, from high-level overviews to detailed diagnostics, enabling agents to analyse outcomes and investigate failures.

A detailed list of all available tools can be found under Tools.

Using the server without a Step instance

A Step instance is not required for every operation. The following tools work entirely locally and can be used without any configured Step instance:

• step_initialize_project: scaffold a new automation package
• step_validate_plan: validate an automation package
• step_execute_automation_package with local=true: run the package locally on your machine

This lets you author, validate and run automation packages locally before connecting to a Step instance. Central execution and the analysis and discovery tools still require a configured Step instance.

Installation

Prerequisites

Before using the Step MCP Server, ensure you have:

• Node.js 20 or newer (Node 24 LTS recommended)

• An MCP-compatible client:

  • Claude Code
  • Claude Desktop
  • VS Code
  • IntelliJ IDEA
  • Any MCP-compatible client

• The Step CLI installed and on your PATH (required only for the execution tool)

For the tools that interact with a Step instance (central execution, analysis and discovery), you additionally need:

• A Step instance, version 28 or later, running in:

  • SaaS cluster
  • On-premises

• Valid Step credentials: STEP_BASE_URL, STEP_PROJECT and STEP_API_KEY (how to generate an API key)

These are not needed if you only use the tools working without a Step instance.

Security: Treat STEP_API_KEY as a secret — never commit it to source control.

Simple Installation

npm install -g step-mcp-server@latest

Client Setup

Register the server in your MCP client and pass your Step connection details as environment variables.

If you only want to use the tools working without a Step instance, you can omit the environment variables, for example:

claude mcp add step -- step-mcp-server

You can add the connection details later, when you need to work with a Step instance.

Claude Code

claude mcp add step \
  -e STEP_BASE_URL=https://your-step-instance/ \
  -e STEP_API_KEY=<your-api-token> \
  -e STEP_PROJECT=<your-project-name> \
  -- step-mcp-server

Claude Desktop

{
  "mcpServers": {
    "step": {
      "command": "step-mcp-server",
      "env": {
        "STEP_BASE_URL": "https://your-step-instance/",
        "STEP_API_KEY": "<your-api-token>",
        "STEP_PROJECT": "<your-project-name>"
      }
    }
  }
}

VS Code

code --add-mcp '{"name":"step","command":"step-mcp-server","env":{"STEP_BASE_URL":"https://your-step-instance/","STEP_API_KEY":"<your-api-token>","STEP_PROJECT":"<your-project-name>"}}'

IntelliJ IDEA (and other JetBrains IDEs)

JetBrains IDEs support MCP through AI Assistant (IntelliJ IDEA 2025.1 and later). Open Settings → Tools → AI Assistant → Model Context Protocol (MCP) and add a server with:

• Command: step-mcp-server
• Environment Variables: STEP_BASE_URL, STEP_API_KEY, STEP_PROJECT

Use the Level option to make it available globally or only in the current project.

Other MCP Clients

Any client that supports stdio MCP servers can run step-mcp-server with the three environment variables above (or without them for the tools working without a Step instance).

Verify your setup

After saving the configuration, reload or restart your MCP client.

From the terminal — confirm step is connected:

claude mcp list

step should appear with status connected.

In Claude Code — confirm the tools are available:

What Step tools do you have?

You should see the step_* tools listed. If they don’t appear, see Troubleshooting.

Advanced Configuration

For multiple Step instances or projects, see Multi-Profile Configuration.

Quick Start

Make sure your Step instance is awake before issuing prompts — the MCP server talks to it directly and will fail immediately if it is unreachable.

Ask the agent to find a failed run and investigate it (or reference a specific run by its execution ID):

Find my most recent failed execution and tell me why it failed.
Start with an overview, then drill into the failing steps and
summarise the root cause.

The agent will:

1. Locate the execution (step_search_executions).
2. Pull a failure-focused overview (step_fetch_execution_overview).
3. Drill into specific failures, attachments, or metrics (step_fetch_execution_report_nodes, step_fetch_report_node, step_download_attachment_content, step_query_performance_metrics).
4. Return a root-cause summary.

A typical response (illustrative):

Execution 67a1f3e9c2b4d5e6f7a8b9c0 failed: 3 of 142 steps errored, all inside
the "Checkout" keyword.

Root cause: the payment-gateway call returned HTTP 503 on every attempt
(stack trace in attachment on ReportNode rn-8842). All three failures share a
single artefactHash, so this is one systemic issue, not flaky tests.

Suggested next step: confirm the payment-gateway environment was available
during the run window (12:04–12:07 UTC).

Tutorial

For a full end-to-end walkthrough — authoring, execution, analysis — including a demo, see the AI-assisted testing tutorial.

Available Tools

Tool reference — Discovery, Authoring, Execution, Analysis, Prompts, and Resources — see Tools.

Data & privacy

The Step MCP Server is a thin bridge to your Step instance. It never calls a large language model (LLM) itself. It returns execution data to your MCP client, which forwards it to whichever model you have configured in your AI agent that acts as the MCP client. You therefore control where the data goes: point your client at a corporate-approved or self-hosted model to keep evidence inside your boundary.

What is sent to the model. To diagnose failures, the analysis tools surface execution evidence: failure summaries, report nodes and the values they produced (keyword input and output, echo texts, assertion values, etc.), performance metrics, and, when explicitly requested, attachment contents such as logs and stack traces. This data can contain sensitive information (internal hostnames, request payloads, secrets logged by the system under test), so treat the model context accordingly.

Access and permissions. The analysis tools are read-only: they query executions, reports, and metrics and never modify anything in Step, so a token with read access to the target project is enough. The execution tool (step_execute_automation_package) starts runs, so it needs a token with permission to run automation packages. It also requires the Step CLI on PATH and a built package on the machine running the server. The authoring tools require permission to deploy packages. Grant the least privilege your usage needs.

Troubleshooting

Server fails to start

• Node.js: ensure Node.js 20+ is installed and step-mcp-server is on your PATH (npm install -g step-mcp-server@latest).
• Client compatibility: confirm your client supports stdio-based MCP servers.

Tool calls fail

If the server starts but tools return errors:

• No Step configuration: without the STEP_BASE_URL environment variable or a configuration file at ~/.step-mcp/config.yaml, the server still starts, but only the tools working without a Step instance can be used. Tools requiring a Step instance return an error. See Client Setup.
• Invalid configuration: a malformed YAML file, a profile missing base_url, a default_profile that names no profile, or a configuration file combined with the STEP_BASE_URL / STEP_API_KEY environment variables doesn’t prevent the server from starting. The server logs a warning and behaves as if no Step instance were configured: tools requiring a Step instance return an error describing the configuration problem.
• Cluster sleeping: if your Step instance is on a SaaS cluster, it may be asleep. Wake it up before retrying.
• Check the resolvedContext field in the tool response — every tool returns a { profile, baseUrl, project } block showing which instance and project the call actually targeted. For tools that ran without a Step instance, resolvedContext is null and a stepConnection block explains why.
• Confirm the resolved base_url is reachable from your machine (network, firewall/proxy, DNS).
• Verify the API token is valid and — on Step Enterprise — that the project exists and is accessible to that token. Use step_list_profiles and step_list_projects to check what is configured and available.
• “No Step profile could be resolved” or “No Step project could be resolved”: pass a profile / project argument, set STEP_PROFILE, or configure a default_profile / default_project in the configuration file. The error lists the available options.

FAQ

Do I need a Step instance?

Not for all operations. Scaffolding, validating and locally executing automation packages work without a Step instance, see Using the server without a Step instance. Central execution, analysis and discovery require one.

Do I need a Step Cloud account?

No. Step MCP supports both Step Cloud and on-premises Step deployments.

Which MCP clients are supported?

Any client that supports stdio-based MCP servers.

Can multiple agents use the same Step instance?

Yes, provided they have valid credentials and the necessary permissions.

Can I connect to multiple Step instances or projects?

Yes. Define a profile per instance in a configuration file and select one per request with the profile argument (or STEP_PROFILE / default_profile). Within an instance, the project argument selects the project, falling back to the profile’s default project. This avoids needing a separate server per project.

Where should credentials be configured?

For simple setup, see Client Setup above. For multiple instances or many projects, use a configuration file with profiles; reference tokens via token_env to keep secrets out of the file.

Can Step MCP analyse failures automatically?

Yes. The Analysis capability gathers execution evidence and helps identify probable failure causes.

Support & feedback

The Step MCP Server is under active development; authoring is planned. For questions, early access, or to report an issue, contact us at contact@exense.ch.