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 Testing 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.

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)

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

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

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.

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.

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_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 artifactHash, 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, and Prompts — 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, 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

  • No configuration found: the server needs either the STEP_BASE_URL environment variable or a configuration file at ~/.step-mcp/config.yaml. If neither is present it exits with a “No Step configuration found” message. See Client Setup.
  • Invalid config file: malformed YAML, a profile missing base_url, or a default_profile that names no profile stops startup with a descriptive error.
  • 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:

  • 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.
  • 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 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.

Categories: AI DEVELOPER GUIDE DEV OPS ENTERPRISE

See Also