MCP server for coding agents

testorim mcp is a Model Context Protocol server. It lets a coding agent run a Testorim test in a real browser and read the result without leaving the editor: the agent makes a change, deploys a preview, asks Testorim to check it, and gets back a verdict with evidence. It ships in the same npm package as the CLI and the JavaScript library, @testorim/cli (version 0.3.0 or later), and is listed in the official MCP Registry as io.github.sallar-ba/testorim.

What the agent can do

Tool	What it does
`list_projects`	Lists the projects (sites under test) in the API key’s workspace. Read-only.
`list_tests`	Lists a project’s saved tests (procedures). Read-only.
`run_test`	Runs a saved test, or any test described in plain English, and waits for the verdict.
`get_run`	Reads a run’s status, verdict, failing steps, report and evidence links. Read-only.
`cancel_run`	Stops a queued or running run. A cancelled run has no verdict.
`create_project`	Adds a site to test. If the workspace already tests that address, returns the existing project.

run_test takes either a testId (a saved test) or a description in plain English, plus an optional baseUrl to run against another address such as a pull request’s preview deployment, an optional expectation of fail for a negative test, and wait / timeoutSeconds (it waits up to 10 minutes by default and sends progress updates while it waits).

Set it up

Create an API key

In Testorim, open Settings → API keys and create a key. It starts with tst_live_. See Authentication for what a key may and may not change.

Add the server to your agent

Agents start MCP servers without your shell’s environment, so put the key in the agent’s own MCP configuration, as below. Replace tst_live_... with your key.

Ask the agent to test

For example: “Deploy a preview, then use Testorim to check that a new user can sign up and reach the dashboard.”

claude mcp add testorim -e TESTORIM_API_KEY=tst_live_... -- npx -y @testorim/cli mcp

[mcp_servers.testorim]
command = "npx"
args = ["-y", "@testorim/cli", "mcp"]
env = { TESTORIM_API_KEY = "tst_live_..." }

{
  "mcpServers": {
    "testorim": {
      "command": "npx",
      "args": ["-y", "@testorim/cli", "mcp"],
      "env": { "TESTORIM_API_KEY": "tst_live_..." }
    }
  }
}

{
  "servers": {
    "testorim": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@testorim/cli", "mcp"],
      "env": { "TESTORIM_API_KEY": "tst_live_..." }
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json), Antigravity (Manage MCP servers, then View raw config), Gemini CLI (~/.gemini/settings.json) and Claude Desktop (claude_desktop_config.json) take the same mcpServers block as Cursor. If your workspace lives on another host, add TESTORIM_API_URL to the same env block.

What comes back

A run_test or get_run reply starts with the verdict and the counts, then the run’s link, each failed step with the reason it failed, links to the video and Playwright trace, and the written report:

Verdict: FAILED (3 passed, 1 failed, 2 skipped, 41s)
Run: https://app.testorim.com/runs/...
Failed step 4: click "Create account": The click changed nothing on the page [the app did not behave as described]
Evidence (links expire after an hour): video ...; Playwright trace ...

The same information is also returned as structured data (verdict, counts, failedSteps with a blame field, runUrl, videoUrl, traceUrl) for agents that read it.

Verdict	Meaning
passed	Every step ran, and the report confirms the request was met.
failed	A step failed. Each failed step says who was at fault: the app did not behave as described; the test could not do what it described (check the wording against the page); the check asked for is not supported; or a Testorim internal error, not your app.
needs_review	Every step passed, but the report could not confirm the request was met.
cancelled	The run was stopped; it has no verdict.

The server’s instructions tell the agent to treat a failure as a real finding only when it is attributed to the app, and to fix the wording of the test when the test was at fault. See Run status for how verdicts are decided.

Limits

The site has to be reachable from the internet. Testorim’s browsers refuse localhost and private addresses. Test a preview deployment by passing its address as baseUrl, or expose your dev server through a tunnel.

Runs count against your plan. A run started by an agent is a run like any other; refusals (a plan limit, every browser busy) come back to the agent as an error with the same code the API uses.
An API key runs and reads. Creating or editing saved tests and settings happens in the app.
Evidence links expire after an hour. The run page keeps the evidence.
Websites only. No native mobile or desktop apps.

Troubleshooting

What the agent sees	What to do
`HTTP 401` and a note about the API key	The key is missing, wrong or revoked. Check the `env` block of the agent’s MCP configuration.
`Could not reach Testorim at ...`	A network problem, or `TESTORIM_API_URL` points at the wrong host.
`code: concurrency_limit`	Your plan’s runs-at-once limit. Wait for a run to finish, or cancel one with `cancel_run`.
The agent does not list the Testorim tools	Restart the agent after adding the server, and check that `npx -y @testorim/cli mcp` starts in a terminal (it waits silently for input; press Ctrl+C to stop it).

​What the agent can do

​Set it up

​What comes back

​Limits

​Troubleshooting

What the agent can do

Set it up

What comes back

Limits

Troubleshooting