Skip to content

Endform MCP server

The Endform CLI includes a local Model Context Protocol (MCP) server. It gives AI coding agents tools for analyzing historical test data, inspecting and replaying test attempts, managing quarantine rules, running tests, and debugging a Playwright test on Endform’s remote infrastructure. Each tool is named after the CLI command that does the same thing.

Authenticate the Endform CLI first:

Terminal window
npx endform@latest login

Then add Endform as a local MCP server in your AI coding tool:

Run this command from your project directory:

Terminal window
claude mcp add --transport stdio --scope local endform -- npx -y endform@latest mcp

Restart the AI coding tool or reload its MCP servers after changing the configuration. The server must run from your project so that its debugging tools can locate your Playwright configuration and tests.

These tools query the same suite and test history that powers the Endform dashboard. See Investigate test history with AI for example conversations.

Lists the organizations available to the active Endform login. Agents can use it when another tool asks for organization selection.

Compares run counts, pass rates, and durations over time. Results are returned as time series with count, percent, or seconds as the unit.

Parameter Type Description
dataset suite-runs or test-runs Aggregate complete suite runs or individual test runs.
metric count, pass-rate, or average-duration Metric to calculate.
groupBy outcome, branch, test, or project Optional grouping. Suite runs cannot be grouped by test or project.
where string Optional filter expression, such as testRun.outcome = fail, branch = main.
period string Positive integer followed by H, D, W, or M. Defaults to 7D.
endingAt ISO 8601 string Optional end of the time window. Defaults to the current time.
organizationId string Optional organization. Omit it to use the organization from the active login.

Returns concrete suite-run or test-run executions matching a filter. Test-run samples include the test identity, project, outcome, duration, and every attempt in chronological order. Each attempt has an id to pass to test_attempt_inspect, and may contain an error message and error location.

Parameter Type Description
dataset suite-runs or test-runs Return complete suite runs or individual test runs.
where string Optional filter expression, such as testRun.testAttemptsCount > 1.
period string Positive integer followed by H, D, W, or M. Defaults to 7D.
endingAt ISO 8601 string Optional end of the time window. Defaults to the current time.
limit number Number of newest records to return. Defaults to 10; maximum 50.
cursor string Optional nextCursor from an earlier response for pagination.
organizationId string Optional organization. Omit it to use the organization from the active login.

Filters are comma-separated clauses. String fields support operators such as =, !=, ^=, $=, ~=, !~=, in, and !in; numeric fields support comparisons such as >, >=, <, and <=. The tool’s input schema contains the complete field and operator reference.

These tools show an agent what a single test attempt did, and let it show you. Find a test attempt ID with samples_query. The run data lives in Endform, so they work for branches that aren’t checked out or pushed.

Inspects a test attempt: what it did, where and how it failed, and how it compares with a passing run. By default, a failed attempt is compared with a passing retry in the same test run when there is one, and otherwise with recent passing runs on the suite’s default branch.

The result contains the attempt’s test and error, its steps aligned with the compared run’s steps, the first step that changed and the step that failed, and one step’s screenshot from both runs. The tool also downloads both runs’ traces and screenshots and writes steps.json, which maps each step to its span and screenshot in both runs, so the agent can read further without another call.

Parameter Type Description
testAttemptId string The test attempt to inspect, from samples_query.
compareWith auto or none auto, the default, picks a passing run to compare with. none skips the comparison, which is faster when the agent only needs what happened.
branch string Optional branch to compare with instead, such as a pull request’s base branch.
compareTestAttemptId string Optional test attempt to compare with instead, such as a passing run found with samples_query.
stepIndex number Optional step to return screenshots for, by its index in the step list. Defaults to the first change, else the failed step.
outputDirectory string Optional absolute directory to download the files into. Defaults to the system temporary directory.
organizationId string Optional organization. Omit it to use the organization from the active login.

Creates a replay link that shows a test attempt’s run step by step with screenshots. The replay can play the attempt beside another attempt’s run, and can open on a chosen span with a caption. Agents use it after test_attempt_inspect to show you the moment that explains a failure or a change.

The result contains a player URL to embed in an iframe and a URL for the full replay in a browser. Both work without a login until expiresAt.

Parameter Type Description
testAttemptId string The test attempt to show, from samples_query or test_attempt_inspect.
compareTestAttemptId string Optional test attempt whose run plays beside this one, such as the one test_attempt_inspect compared with.
compareLabel string Optional name for the run beside this one, such as Passing retry. Requires compareTestAttemptId. Defaults to its outcome and branch.
spanId string Optional span to open on and mark, such as a step’s spanId from test_attempt_inspect or steps.json.
spanLabel string Optional caption for the marked span, at most 80 characters. Requires spanId.
at end or start Open on the span’s result (end, the default) or its start. Requires spanId.
organizationId string Optional organization. Omit it to use the organization from the active login.

These tools let an AI agent list, create, update, and deactivate quarantine rules. See Modify quarantine rules with AI for example conversations.

Lists active quarantine rules and their exact rule IDs, scope, reason, and expiry.

Parameter Type Description
organizationId string Optional organization. Omit it to use the organization from the active login.
includeInactive boolean Include expired and deactivated rules. Defaults to false.

Creates a quarantine rule for an exact suite and scope. Use samples_query to retrieve the persisted suite.id and, when selecting a test, test.id. Test names, file paths, and Playwright worker IDs are not test IDs.

Parameter Type Description
suiteId string Exact persisted suite.id returned by samples_query.
testId string Optional exact persisted test.id. Omit it to match all tests in the suite.
projectName string Optional exact Playwright project name.
branch string Optional exact branch name.
reason string Optional reason for quarantining the matching tests.
endsAt RFC 3339 string Optional future expiry timestamp. Omit it for no expiry.
organizationId string Optional organization. Omit it to use the organization from the active login.

In addition to suiteId, provide at least one of testId, projectName, or branch. Omitted scope fields match any value within the suite.

Replaces all editable settings of an active quarantine rule, keeping its ID and its priority among overlapping rules. Use quarantine_list to retrieve the ID. The suite cannot change, and inactive rules cannot be edited.

Parameter Type Description
ruleId string Exact quarantine rule ID returned by quarantine_list.
testId string | null Exact persisted test.id, or null to match all tests in the suite.
projectName string | null Exact Playwright project name, or null to match any project.
branch string | null Exact branch name, or null to match any branch.
reason string | null Reason for quarantining the matching tests, or null to clear it.
endsAt RFC 3339 string | null Future expiry timestamp, or null for no expiry.
organizationId string Optional organization. Omit it to use the organization from the active login.

Supply every editable field explicitly. At least one of testId, projectName, or branch must remain set.

Deactivates one quarantine rule by its exact ID. Use quarantine_list to retrieve the ID.

Parameter Type Description
ruleId string Exact quarantine rule ID returned by quarantine_list.
organizationId string Optional organization. Omit it to use the organization from the active login.

These tools let an AI agent run tests or a whole suite on Endform from your project, as endform test does, and follow the run while it carries on in the background.

Starts a suite run from a local project directory and returns as soon as the suite has started, with a suiteRunId. Omit testFileFilters, grep, grepInvert, and project to run the whole suite.

Parameter Type Description
directory string Absolute path of the directory to run from, as if endform test were started there.
testFileFilters string[] Playwright-style regular expressions matched against absolute test paths. A filter may include a declaration line, such as tests/checkout.spec.ts:47.
grep string[] Include tests whose full title chain matches these regular expressions.
grepInvert string[] Exclude tests whose full title chain matches these regular expressions.
project string[] Include tests from these Playwright projects.
repeatEach number Run each selected test this many times, like Playwright’s --repeat-each.
maxFailures number Stop the suite after this many failures. Defaults to the Playwright configuration; 0 removes the limit.
retries number Maximum retries for each failed test. Defaults to the Playwright configuration.
config string Optional Playwright configuration file or test directory. Relative paths resolve against directory.
organizationId string Optional organization. Defaults to the organization configured for the repository or the active login.

To measure how flaky a test is, an agent can select it, set retries to 0, and repeat it with repeatEach, for example 100 times before a fix and 100 times after.

Shows the progress of a suite run. status is running until the tests and local cleanup have finished, then passed, failed, stopped, or error. Failures, the report URL, and the local results path are set once the run is over.

Parameter Type Description
suiteRunId string Suite run returned by suite_run_start.

Use status to tell whether the suite passed. The failed count can include quarantined tests.

Stops a suite run, cancels its remaining tests, cleans up its local web servers, and returns the final status. Stopping a run that is already over returns its status.

Parameter Type Description
suiteRunId string Suite run returned by suite_run_start.

These tools let an AI agent pause inside one Playwright test and inspect or interact with its live browser state. See Debug tests with AI for example conversations.

Starts a remote live session and pauses at a checkpoint inside exactly one matching test. Startup can take a few minutes. The response includes a sessionId, the checkpoint location, result and log paths, and an initial ARIA snapshot of the page.

Parameter Type Description
testFileFilters string[] Playwright-style regular expressions matched against absolute test paths. A filter may include a declaration line, such as tests/checkout.spec.ts:47.
grep string[] Include tests whose full title chain matches these regular expressions.
grepInvert string[] Exclude tests whose full title chain matches these regular expressions.
project string[] Include tests from these Playwright projects.
line number 1-based source line to pause before. Defaults to the first statement in the test body.
config string Optional Playwright configuration file or test directory.
organizationId string Optional organization. Defaults to the organization configured for the repository or the active login.

The selection must resolve to one test. Sessions end automatically after 15 minutes.

Runs JavaScript inside the paused test’s scope. The code can use await and test fixtures such as page. The agent can call this repeatedly to inspect locators, read application state, interact with the page, or create screenshots.

Parameter Type Description
sessionId string Session returned by live_test_start.
code string JavaScript to evaluate at the checkpoint.

Each call returns standard output, standard error, an exit code, a fresh ARIA snapshot, and paths to newly created artifacts. A non-zero exit code means the code threw; the session remains paused.

Returns the current session state: starting, paused, running, ended, or stale. A paused response includes a fresh ARIA snapshot.

Parameter Type Description
sessionId string Session returned by live_test_start.

Stops a live session and cleans up its local and remote resources. Agents should call it when debugging is complete rather than waiting for the 15-minute limit.

Parameter Type Description
sessionId string Session returned by live_test_start.