Testorim MCP server

Your agent writes the change. Testorim says if the site still works.

testorim mcp is a Model Context Protocol server for coding agents. The agent asks for a test in plain English; Testorim runs it in a real browser and hands back a verdict with evidence. The agent gets an answer, not a browser to drive.

Join the waitlist See the setup

Free, MIT-licensed CLI
Node.js 20 or newer
MCP over stdio

agent sessiontestorim mcp

> Deploy a preview, then check that a new user can sign up.

testorim · run_test

baseUrl: https://pr-128.preview.example.com
description: "Sign up with a new email address and check that the dashboard opens and says Welcome."

Failed3 passed, 1 failed, 2 skipped

Step 4click "Create account"

The click changed nothing on the page: the address stayed on /signup and no message appeared.

The app did not behave as described

VideoTrace

Illustration. The address and messages are made up to show the shape of a reply.

Works with

Claude Code
OpenAI Codex
Cursor
GitHub Copilot in VS Code
Windsurf
Google Antigravity
Gemini CLI

Product names and logos belong to their owners; shown to indicate compatibility.

Where it sits in the agent's loop.

The agent keeps writing the code. Testorim is the step that checks the result in a real browser, so the agent is not the one deciding what passed.

1
1The agent changes the code.
It writes the fix or the feature you asked for, as it does today.
2
2It deploys a preview.
Testorim's browsers need a public address, so the change goes to a preview deployment or through a tunnel.
3
3It calls run_test.
With the preview's address as baseUrl and a plain-English description of what a visitor should be able to do.
4
4It reads the verdict.
Passed, it ships. Failed on the app's side, it fixes the code and runs the same test again.

Six tools.

The server ships inside the @testorim/cli package, which has no runtime dependencies and needs Node.js 20 or newer. It speaks MCP over stdio and calls the same API as the CLI, so the agent can do what an API key can do: run tests and read results.

list_projectsRead-only
Lists the projects (sites under test) in the API key's workspace, with each one's id and address.
list_testsRead-only
Lists a project's saved tests. A saved test replays its recorded steps without planning them again.
run_testStarts a run
Runs a saved test, or any test described in plain English, in a real browser, and waits for the verdict.
get_runRead-only
Reads a run's status, verdict, failing steps, report and evidence links.
cancel_runStops a run
Stops a queued or running run. A cancelled run has no verdict.
create_projectAdds a project
Adds a site to test. If the workspace already tests that address, it returns the existing project.

What run_test takes.

The one tool that starts a run. Everything but the test itself is optional.

testId or description: A saved test, or a plain-English description of one. Never both.
baseUrl: Points one run at another address, such as a pull request's preview deployment.
expectation: "fail": Makes it a negative test, where a wrong password must be refused.
timeoutSeconds: It waits up to ten minutes for the verdict by default, and up to thirty with this set.
wait: false: Returns the run id at once, to read later with get_run.

Set it up in your agent.

1
Create an API key.
In Testorim, under Settings, API keys.
2
Add the server to your agent.
Pick your agent below and copy its snippet. Replace tst_live_... with your key.
3
Ask the agent to test a preview.
For example: deploy a preview, then use Testorim to check that a new user can sign up and reach the dashboard.

One command, in a terminal:

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

Add this to ~/.codex/config.toml:

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

Add this to .cursor/mcp.json:

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

Add this to .vscode/mcp.json:

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

Add this to ~/.codeium/windsurf/mcp_config.json:

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

In Manage MCP servers, open View raw config and add:

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

Add this to ~/.gemini/settings.json:

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

Add this to claude_desktop_config.json:

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

Agents start MCP servers without your shell's environment, so the key goes in each agent's own config rather than in an exported variable.

If your workspace lives on another host, add TESTORIM_API_URL to the same env.

What an exchange looks like.

A failure the app caused, the agent's fix, and the same test passing on the next preview.

Illustrative example. The project, addresses, counts and messages are made up to show the shape of a reply; they do not come from a real run.

Agent sessiontestorim mcp

You
Fix the sign-up form, deploy a preview, then use Testorim to check that a new user can sign up and reach the dashboard.
Agent
calls run_test(projectId: "...", baseUrl: "https://pr-128.preview.example.com", description: "Sign up with a new email address and check that the dashboard opens and says Welcome.")
Testorim
Failed3 passed, 1 failed, 2 skipped
Run
https://app.testorim.com/runs/...
Started at
https://pr-128.preview.example.com/signup
Step 4click "Create account"
The click changed nothing on the page: the address stayed on /signup and no message appeared.
The app did not behave as described
VideoTraceLinks expire after an hour
Agent
The failure is on the app's side, not the test's. The submit handler returns early because the new company field is required and the form never renders it. Fixed, pushed, and running the same test on the new preview.
Testorim
Passed6 passed, 0 failed, 0 skipped

What the verdict means.

Every run ends in one of these. The server tells the agent to treat a failure as a real finding only when it is attributed to the app. That matters: an agent that sees red has two ways to make it green, and only one of them fixes your site.

Passed: Every step ran, and the report confirms the request was met.
Failed: A step failed. Each failed step carries one of four labels:
The app did not behave as described.
The test could not do what it described, so check the wording against the page.
The check asked for is not supported.
A Testorim internal error, not your app.
A mismatch Testorim cannot pin on either side is marked unconfirmed.
Needs review: Every step passed, but the report could not confirm the request was met. Worth a human look before anyone calls it green.
Cancelled: Stopped before it finished, so there is no verdict.

Limits worth knowing first.

It needs a public address.
Testorim's browsers refuse localhost and private addresses. Test a preview deployment by passing its address as baseUrl, or put your dev server behind a tunnel.
Runs count against your plan.
A run started by an agent is a run like any other. There is no free plan, and every plan starts with a 3-day trial that needs a card.
Websites only.
No native mobile or desktop apps.
An API key runs and reads.
An API key can run tests and read results. Editing saved tests and settings happens in the app. Evidence links in a reply expire after an hour; the run page keeps the evidence.

Plans and what a run counts as are on the pricing page. Comparing this with a browser your agent drives itself? Read the Playwright MCP guide.

Quick answers

What does Testorim's MCP server do?

It lets a coding agent run an end-to-end test of your website and read the result. The agent describes what a visitor should be able to do, or picks a saved test; Testorim runs it in a real browser and returns a verdict, the failing steps with who was at fault, a written report, and links to the video and Playwright trace.

Which coding agents does it work with?

Any agent that can start an MCP server over stdio. This page has setup for Claude Code, Codex, Cursor, VS Code, Windsurf, Antigravity, Gemini CLI and Claude Desktop.

Can it test a site running on localhost?

No. Testorim's browsers refuse localhost and private addresses. Deploy a preview and pass its address to run_test as baseUrl, or expose your dev server through a tunnel.

Does the agent have to write test code?

No. run_test takes a plain-English description, such as: sign up with a new email address and check that the dashboard opens and says Welcome. It can also replay a saved test, which repeats its recorded steps without planning them again.

How is this different from Playwright MCP?

Playwright MCP gives the agent a browser to drive on your machine, and the agent decides what passed. Testorim runs the test on its own browsers and returns the verdict with evidence. Playwright MCP can reach localhost and is free and open source; Testorim needs a public address and is a paid service. The two can run side by side in one agent.

What does it cost?

The CLI that contains the server is free and MIT licensed. The runs it starts count against your Testorim plan like any other run. There is no free plan: every plan starts with a 3-day trial that needs a card. Sign-up is currently by waitlist, and the API key comes with an account.

Give your agent a verdict, not a browser.

One command in Claude Code, with an API key from Settings, API keys.

Join the waitlist

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

Your agent writes the change. Testorim says if the site still works.

Where it sits in the agent's loop.

1The agent changes the code.

2It deploys a preview.

3It calls run_test.

4It reads the verdict.

Six tools.

What run_test takes.

Set it up in your agent.

Create an API key.

Add the server to your agent.

Ask the agent to test a preview.

What an exchange looks like.

What the verdict means.

Limits worth knowing first.

It needs a public address.

Runs count against your plan.

Websites only.

An API key runs and reads.

Quick answers

What does Testorim's MCP server do?

Which coding agents does it work with?

Can it test a site running on localhost?

Does the agent have to write test code?

How is this different from Playwright MCP?

What does it cost?

Give your agent a verdict, not a browser.

Keep reading.

Playwright MCP guide

Test your website with AI

AI browser testing

Pricing