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, managing quarantine rules, and debugging a Playwright test on Endform’s remote infrastructure.

Set up the MCP server

Authenticate the Endform CLI first:

npx endform@latest login

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

Claude Code

Run this command from your project directory:

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

OpenCode

Add 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
    }
  }
}

Cursor

Add the server to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "endform": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "endform@latest", "mcp"]
    }
  }
}

VS Code

Add the server to .vscode/mcp.json in your project:

{
  "servers": {
    "endform": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "endform@latest", "mcp"]
    }
  }
}

Other

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.

Non-interactive authentication

Set ENDFORM_API_KEY in the MCP server’s environment instead of running endform login. Do not commit API keys to a project-level MCP configuration.

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.

list_organizations

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

query_analytics

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.

query_samples

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. Attempts may contain an error message, error location, and otelTraceId.

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.

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.

get_otel_trace

Returns raw OpenTelemetry trace data for a test attempt. The trace can show Playwright actions, network activity, timing, and other spans recorded while that attempt ran.

Parameter	Type	Description
traceId	string	The otelTraceId returned by query_samples.

Manage quarantine rules

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

list_quarantine_rules

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.

create_quarantine_rule

Creates a quarantine rule for an exact suite and scope. Use query_samples 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 query_samples.
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.

deactivate_quarantine_rule

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

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

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

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.

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

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

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

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.