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.
Set up the MCP server
Section titled “Set up the MCP server”Authenticate the Endform CLI first:
npx endform@latest loginThen add Endform as a local MCP server in your AI coding tool:
Run this command from your project directory:
claude mcp add --transport stdio --scope local endform -- npx -y endform@latest mcpAdd the server to opencode.jsonc in your project:
{ "$schema": "https://opencode.ai/config.json", "mcp": { "endform": { "type": "local", "command": ["npx", "-y", "endform@latest", "mcp"], "enabled": true } }}Add the server to .cursor/mcp.json in your project:
{ "mcpServers": { "endform": { "type": "stdio", "command": "npx", "args": ["-y", "endform@latest", "mcp"] } }}Add the server to .vscode/mcp.json in your project:
{ "servers": { "endform": { "type": "stdio", "command": "npx", "args": ["-y", "endform@latest", "mcp"] } }}Configure a local stdio server using this command and arguments:
{ "mcpServers": { "endform": { "command": "npx", "args": ["-y", "endform@latest", "mcp"] } }}Your MCP client may use a different key than mcpServers. Follow its instructions for adding a local stdio server.
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.
Analyze historical test data
Section titled “Analyze historical test data”These tools query the same suite and test history that powers the Endform dashboard. See Investigate test history with AI for example conversations.
organization_list
Section titled “organization_list”Lists the organizations available to the active Endform login. Agents can use it when another tool asks for organization selection.
analytics_query
Section titled “analytics_query”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. |
samples_query
Section titled “samples_query”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.
Inspect test attempts
Section titled “Inspect test attempts”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.
test_attempt_inspect
Section titled “test_attempt_inspect”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. |
test_attempt_replay_link
Section titled “test_attempt_replay_link”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. |
Manage quarantine rules
Section titled “Manage quarantine rules”These tools let an AI agent list, create, update, and deactivate quarantine rules. See Modify quarantine rules with AI for example conversations.
quarantine_list
Section titled “quarantine_list”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. |
quarantine_create
Section titled “quarantine_create”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.
quarantine_update
Section titled “quarantine_update”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.
quarantine_deactivate
Section titled “quarantine_deactivate”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. |
Run tests
Section titled “Run tests”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.
suite_run_start
Section titled “suite_run_start”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.
suite_run_status
Section titled “suite_run_status”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.
suite_run_stop
Section titled “suite_run_stop”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. |
Debug tests
Section titled “Debug tests”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.
live_test_start
Section titled “live_test_start”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.
live_test_run
Section titled “live_test_run”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.
live_test_status
Section titled “live_test_status”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. |
live_test_stop
Section titled “live_test_stop”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. |