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

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.

debug_test_start

Starts a remote debug 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.

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

debug_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 debug_test_start.

debug_test_stop

Stops a debug 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 debug_test_start.