Tools

Reference for all tools exposed by the Step MCP Server. For setup and installation, see Getting Started.

All tools accept two optional shared parameters: profile (which Step instance and credentials to use) and project (which project to act on). The discovery tools below are the exception: they don’t require a project. When omitted, parameters fall back to the configured defaults (see Profile and project resolution). Every tool’s response includes a resolvedContext block reporting the profile, baseUrl, and project actually used.

The following tools work without a Step instance and can be used even when no Step instance is configured: step_initialize_project, step_validate_plan and step_execute_automation_package for local executions (local=true). All other tools require a configured Step instance.

Discovery

Read-only tools that let an agent discover valid profile and project names before acting — without reading the configuration file or exposing its secrets.

step_list_profiles

Lists the configured profiles with safe, non-secret metadata: name, base URL, default project, whether a credential is configured, its source (user or workspace file), and which profile is the default. API tokens are never returned. Useful to resolve a human reference (“the build server”) to a profile name before acting. Takes no parameters.

step_list_projects

Lists the projects available for a profile on Step Enterprise, so an agent can pick a valid project before calling a project-scoped tool. On the open-source edition it reports that project listing is not supported.

Key parameters:

  • profile (optional; resolved as usual)

Authoring

Helps an agent assemble a deployable Step Automation Package. The MCP server’s role is deliberately narrow: it provides the building blocks, while the agent produces the test content itself. The authoring tools work locally and don’t require a Step instance.

step_initialize_project

Scaffolds a local Step Automation Package from scratch. The output is shaped by two parameters:

  • keywordSource: prebuilt-library, custom-code, or imported-asset
  • useCase: functional-testing, load-testing, monitoring, or rpa

Every combination is valid.

The generated automation-package.yaml declares the schema version matching the Step version: 1.1.1 for Step 28, 1.2.0 for Step 29 and 30, and 1.3.0 for Step 31. It defaults to 1.3.0.

The tool returns a filesystemReceipt listing all created files. Use dryRun=true to preview without writing to disk. Chain with step_validate_plan after scaffolding.

step_validate_plan

Validates a Step Automation Package at the requested depth. Available values for depth: parse, references, resolve, dry-run — currently only parse (the default) is implemented; the other values fail with a DEPTH_NOT_IMPLEMENTED error. With depth='parse', the tool checks that automation-package.yaml exists, is valid YAML, and conforms to the schema version declared in its version field (or, if the descriptor has none, the one matching the stepVersion parameter). The schema versions 1.2.0 and 1.3.0 are supported; a descriptor declaring another version fails with a SCHEMA_NOT_FOUND error. Schema violations report the offending key or value (for example the unexpected property, or the list of allowed values).

Typically chained directly after step_initialize_project by passing its filesystemReceipt.root as packagePath.

Step version detection

Both authoring tools run on the local file system and only use a Step instance, if one is configured, to detect the server version. Without a Step instance, pass the stepVersion parameter; otherwise the latest stable Step version is assumed. If you explicitly pass a profile, it must resolve to a configured profile.

Execution

Runs a Step Automation Package through the Step CLI, either centrally on a Step instance or locally on your own machine. The Step CLI must be installed and on your PATH.

Note: Local execution runs the package on agents started on your machine and needs no Step instance: it can be used even when no Step instance is configured in the MCP server. Keyword types other than Java require their runtime to be installed, see the prerequisites.

Typical use cases:

  • Run an existing automation package and feed the results straight into Analysis
  • Re-run a package to confirm a fix or reproduce a failure

step_execute_automation_package

Executes a Step Automation Package through the Step CLI (step ap execute --async) and returns immediately with the execution ID(s). Follow up with step_search_executions or step_fetch_execution_overview to track results.

Key parameters:

  • packagePath (required, absolute path to the package folder or a built .tar.gz / .zip archive)
  • local (default false; run the package locally on your machine instead of centrally on the Step server)
  • plans (optional; specific plan names, otherwise all plans run)
  • force (default false; pass --force to bypass CLI/server version-mismatch errors)
  • executionParameters (optional; can be repeated, the execution parameters to pass)

Analysis

Read-only tools that let an agent navigate and diagnose Step execution results in a token-efficient way, from a high-level health overview down to individual failures, attachments, and performance metrics. The same tools work across functional tests, load tests, synthetic monitoring, and custom workflows.

Typical use cases:

  • Diagnose why an execution failed and summarise the root cause
  • Triage a large run by navigating only the failing paths
  • Inspect logs, stack traces, and attachments for a specific failure
  • Investigate performance regressions or resource exhaustion from execution metrics
  • Find past executions by status, time window, user, or parameters

A typical troubleshooting flow:

  1. Find the execution with step_search_executions.
  2. Assess overall health with step_fetch_execution_overview.
  3. Page through individual failures with step_fetch_execution_report_nodes.
  4. Read a single node in full with step_fetch_report_node when values were truncated.
  5. Pull raw evidence (logs, stack traces) with step_download_attachment_content.
  6. Investigate performance with step_query_performance_metrics.

Node values

Besides their status and error, report nodes expose the values they produced, depending on their type:

  • Keyword: input and output (as JSON strings)
  • Echo: the resolved echo text
  • Set: the assigned key and value
  • Assert: key, operator, negated, expected, actual and a human-readable description
  • Check: the evaluated expression
  • For / ForEach / While: iteration count and errorCount; RetryIfFails: tries and skipped
  • Other node types (TestCase, If, Sleep, Sequence, …) report their status and error only. For PerformanceAssert and AssertMetric, the error message contains the actual-vs-expected comparison.

Protected values are masked by Step before being persisted, so the values returned are the same as those displayed in the Step UI.

The analysis tools offer three zoom levels, to be used from top to bottom:

  1. step_fetch_execution_overview: the whole execution as an aggregated tree of counts, with values inlined for every node that ran exactly once.
  2. step_fetch_execution_report_nodes: the individual instances of one node, identified by its artefactHash. Paged, with values capped.
  3. step_fetch_report_node: one single node, identified by its id, with uncapped values.

At levels 1 and 2, each value is capped (maxValueChars, 2048 characters by default, max 20000). Truncated values are listed in the node’s truncatedFields with their full length, and can be read in full with step_fetch_report_node.

step_search_executions

Searches for executions in Step. All filters are optional and combined with AND logic; results are sorted by start time (descending). Useful as an entry point when you don’t already have an execution ID.

Key parameters:

  • description
  • status (RUNNING / PASSED / FAILED / TECHNICAL_ERROR)
  • user
  • startTimeFrom / startTimeTo (epoch ms)
  • executionParameters
  • offset, limit (max 200, default 25)

step_fetch_execution_overview

Assesses the overall health of an execution. Use this first.

Returns a token-optimized view of the Aggregated Tree, showing only the failing paths by default. Set filterStatus to ALL to include passing ones.

Every node reports an instanceCount. Nodes that ran exactly once also carry a singleInstance block with the id, status, error and values of that run. Nodes that ran more than once (loop bodies, retries, parallel threads) report counts only: page through their instances with step_fetch_execution_report_nodes using the node’s artefactHash.

Counts are evaluated within the requested time window. Narrowing startTime / endTime around a failure is the fastest way to get values out of a long run: a keyword that ran 400 times overall but once in the window becomes a single-instance node and has its values inlined.

With includePreview enabled (default), it inlines the values of single-instance nodes and small attachments to avoid extra round trips. Set it to false to get counts only.

Key parameters:

  • executionId (required)
  • filterStatus (FAILED / ALL, default FAILED)
  • includePreview (default true)
  • startTime / endTime (epoch ms, optional; must be provided together, default to the whole execution)
  • maxValueChars (default 2048, max 20000; per-field cap on inlined values)

step_fetch_execution_report_nodes

Pages through more instances of a specific failure by querying the raw execution tree. The artefactHash is a hash identifying a specific failing node type in the Aggregated Tree — returned by step_fetch_execution_overview. Each node returns its values, error message and attachments.

Key parameters:

  • executionId (required)
  • artefactHash (required)
  • limit (default 5)
  • offset (default 0)
  • maxValueChars (default 2048, max 20000; per-field cap on returned values, applied to every node of the page)

step_fetch_report_node

Returns a single report node in full, identified by the id returned in the overview’s singleInstance block or by step_fetch_execution_report_nodes. This is the last level of the drill-down and the only one that doesn’t cap values: use it when a node reported truncatedFields and you need the complete keyword output, assert actual value or echo text. Small text attachments are previewed inline. The response also contains the node’s artefactHash, to navigate back to its sibling instances.

Because nothing is truncated, a node with a large payload can return tens of KB: prefer the listing tools when a preview is sufficient.

Key parameters:

  • executionId (required)
  • reportNodeId (required)

step_download_attachment_content

Downloads the contents of an attachment identified on a ReportNode. Small text files are returned inline. Larger text files and binary files (Playwright trace bundles, HAR files) are saved to disk and the file path is returned.

Key parameters:

  • attachmentId (required)
  • attachmentType (required)

step_query_performance_metrics

Pulls time-series metric aggregates or bucketed histogram data across the execution timeline. Essential for analysing performance regressions, load tests, and resource exhaustion. Start and end times default to the execution window.

Key parameters:

  • executionId (required)
  • metricType (default response-time; also histogram, gauge, counter)
  • numberOfBuckets (max 200, default 100; use 1 for a single aggregate across the whole execution)
  • percentiles (default [80, 90, 99])
  • startTime / endTime (epoch ms, optional)

Prompts

The server registers one MCP prompt that pre-configures an agent for root-cause analysis.

troubleshoot_step_execution

Directs the agent to perform an optimization-first root cause analysis on a Step execution run. It injects a system directive that enforces the recommended workflow:

  1. Call step_fetch_execution_overview (with includePreview=true) first and use the values inlined for single-instance nodes.
  2. For nodes that ran more than once, use step_fetch_execution_report_nodes with their artefactHash (or step_query_performance_metrics for a performance anomaly). On long runs, narrow the overview’s time window around the failure instead.
  3. Use step_fetch_report_node only to read truncated values of a single node in full.
  4. Never brute-force raw nodes when an aggregation map is available.

Argument:

  • executionId (required)

Resources

The server exposes the following MCP resources, which agents can read as background context:

  • Step data model fundamentals (step://docs/data-model): explains the Aggregated Tree, report nodes, node values and the recommended drill-down strategy.
  • Automation package schema (step://schema/ap/{version}): the JSON schema of the automation-package.yaml descriptor for each bundled schema version: step://schema/ap/1.2.0 and step://schema/ap/1.3.0. Useful for an agent authoring or fixing an automation package. Available without a Step instance.