> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testorim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server for coding agents

> Let Claude Code, Codex, Cursor and other coding agents run a Testorim test and read the verdict.

`testorim mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) 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](/developers/cli) and the [JavaScript library](/developers/javascript), `@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

<Steps>
  <Step title="Create an API key">
    In Testorim, open **Settings → API keys** and create a key. It starts with `tst_live_`. See [Authentication](/developers/authentication) for what a key may and may not change.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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."*
  </Step>
</Steps>

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add testorim -e TESTORIM_API_KEY=tst_live_... -- npx -y @testorim/cli mcp
  ```

  ```toml Codex (~/.codex/config.toml) theme={null}
  [mcp_servers.testorim]
  command = "npx"
  args = ["-y", "@testorim/cli", "mcp"]
  env = { TESTORIM_API_KEY = "tst_live_..." }
  ```

  ```json Cursor (.cursor/mcp.json) theme={null}
  {
    "mcpServers": {
      "testorim": {
        "command": "npx",
        "args": ["-y", "@testorim/cli", "mcp"],
        "env": { "TESTORIM_API_KEY": "tst_live_..." }
      }
    }
  }
  ```

  ```json VS Code (.vscode/mcp.json) theme={null}
  {
    "servers": {
      "testorim": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@testorim/cli", "mcp"],
        "env": { "TESTORIM_API_KEY": "tst_live_..." }
      }
    }
  }
  ```
</CodeGroup>

**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:

```text theme={null}
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](/test-execution/run-status) for how verdicts are decided.

## Limits

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

* **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](/api-reference/errors) 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). |


## Related topics

- [JavaScript and TypeScript library](/developers/javascript.md)
- [CLI](/developers/cli.md)
- [Python package and pytest](/developers/python.md)
- [FAQ](/resources/faq.md)
- [Platform overview](/developers/platform-overview.md)