MCP Server

Checksum runs a hosted MCP server, so any MCP-capable coding agent can drive Checksum directly. Connect once, then just ask in plain English:

“Generate Checksum tests for this PR.” “My checkout test is failing — heal it.” “Why did the last test run fail?”

The work runs in Checksum’s cloud and comes back as a pull request — no local test engine, no Playwright install, nothing running on your machine.

New to MCP? MCP is a standard way for AI coding assistants to use outside tools. Connecting Checksum over MCP means your assistant — Claude Code, Cursor, Copilot — can generate and fix tests for you just by being asked. You don’t need to understand the protocol to use it; you connect once and then talk normally.

Server URL

https://api.checksum.ai/public-api/mcp

This complements Coding Agent Integration rather than replacing it. Those slash commands run locally against your repo (and can also detect test cases). The MCP server triggers cloud generation and healing, with nothing to install.

Before you start

You need all three:

A Checksum project that’s set up — environment URL, test users, and Git connected. If you haven’t done that yet, start with Getting Started; the MCP server has nothing to act on without it.
You’re logged in to app.checksum.ai in your browser. The approval screen needs an active session.
An MCP-capable client — Claude Code, Cursor, VS Code (Copilot), Claude desktop/web, or any other MCP client.

Connect your client

You sign in through your browser and approve which projects the client may use. There’s no API key to copy, paste, or accidentally commit.

Claude Code
Cursor
VS Code (Copilot)
Claude (web & desktop)
Anything else

Install the Checksum plugin — it adds the connection plus skills that know how to push your branch and find the right pull request before a cloud run:

/plugin marketplace add checksum-ai/plugins
/plugin install checksum@checksum-ai

Then run /mcp, pick checksum, and approve in the browser.

Just the server, without the plugin

claude mcp add --transport http checksum https://api.checksum.ai/public-api/mcp

Then run /mcp and pick checksum to sign in.

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json to enable it everywhere):

{
  "mcpServers": {
    "checksum": {
      "url": "https://api.checksum.ai/public-api/mcp"
    }
  }
}

Restart Cursor. Open the MCP settings from Customize, find checksum, and click to sign in.

Create .vscode/mcp.json in your project:

{
  "servers": {
    "checksum": {
      "type": "http",
      "url": "https://api.checksum.ai/public-api/mcp"
    }
  }
}

VS Code shows a Start action above the server entry — click it and approve in the browser.

Go to Customize → Connectors → Add custom connector, and paste:

https://api.checksum.ai/public-api/mcp

Approve in the browser when prompted. Checksum’s tools then appear in any chat.

On Team and Enterprise plans this lives under Organization settings → Connectors and only an Owner can add it.

Any MCP client works. Point it at the server as a Streamable HTTP server:

https://api.checksum.ai/public-api/mcp

The server advertises browser sign-in automatically, so a compliant client will offer to authenticate. For a client that can only send a static token, see Connect with an API key.

What you’re approving

The browser shows you which projects the client may act on. If you have access to several, you can grant only the ones you want — the client can never reach a project you didn’t approve. Access is re-checked on every request, so if you lose access to a project, the client loses it too. Review or revoke a connection any time from the MCP connections card on My Profile in the web app. A connection is tied to you, not to a project — so it lives with your account, and revoking it cuts the client off from every project you granted.

Check that it worked

Ask your agent, in plain English:

Run checksum_whoami.

It replies with the project you’re connected to and a link to its dashboard. That one call proves the whole chain — client, connection, sign-in, and project access. If it works, you’re done. If it doesn’t, see Troubleshooting.

Push your work first. Checksum generates in the cloud by checking out your repo from your Git provider, so it only ever sees commits you’ve pushed. Ask it to cover code that’s still on your machine and it will happily test the old version, and you’ll wonder why the tests are wrong.Commit and push, then ask. (The Claude Code plugin does this for you.)

What you can ask

Once connected, talk to your agent normally — it picks the right tool. Cover a pull request:

Generate Checksum tests for PR 142 in acme/web on branch feature/checkout.

Cover a flow you just built:

Generate a Checksum test for the login flow with an invalid password.

Fix failing tests:

My latest Checksum run has failures — heal them and open a PR.

Investigate a failure before fixing it:

Why did the last Checksum run fail? Pull the report and show me the failing test.

Steer a run that’s already going:

Tell the Checksum session to also cover the "expired card" case.

Checksum only opens a pull request for a PR-based run — one where it knows the pull request number, the repository, and the branch. Ask it to generate tests for a flow you describe and it will do that, but the tests land in the session for review rather than in a PR.

Tools

Your agent picks these automatically; you rarely name them yourself. They’re listed so you know what the server can and can’t do.

Tool	What it does
`checksum_whoami`	Confirms your connection and lists the projects you’re authorized for.
`checksum_test_generate`	Starts a test-generation run — for a pull request, or for a flow you describe. Returns a `batchId`.
`checksum_test_heal`	Starts an auto-heal run for the failing tests in a test run. Returns a `batchId`.
`checksum_session_status`	Reports a run’s progress, what the agent is doing, the files it changed, and the `prUrl` it opened. Your agent calls this repeatedly until the run finishes.
`checksum_test_run_list`	Lists recent test runs, newest first — how the agent finds a failing run without you hunting for an id.
`checksum_test_run_download`	Gets a run’s results inline, plus a download link for the HTML report. Pass a specific test to also get its trace, screenshots and video.
`checksum_session_list`	Lists recent agent sessions.
`checksum_session_prompt`	Sends a follow-up instruction into a running session — how you steer an agent mid-run.

checksum_whoami, checksum_session_status, checksum_test_run_list, checksum_test_run_download and checksum_session_list are read-only. checksum_test_generate, checksum_test_heal and checksum_session_prompt change things — they start billable cloud runs and can open pull requests, so a good client will ask you to confirm before running them. Every result comes back with links straight into the Checksum web app, so you can watch a session or open a run rather than squinting at ids.

Generating tests

Give checksum_test_generate either a pull request — the number, the repository, and the branch, all three — or extraInstructions describing the flow to cover.Those three fields together are what make Checksum open a pull request with the generated tests. A description-only run doesn’t open one; the tests land in the session for you to review first.Asking twice for the same pull request won’t start a second run — it picks up the one already going.You can also point a run at a different environment (a preview deployment, say) with envOverrides.

Healing failing tests

checksum_test_heal needs the testRunId of a run that has failures — ask your agent to list recent runs if you don’t have one to hand. It opens one heal session covering all the failing tests in that run and, by default, a pull request with the fixes.Healing works from a run that already finished, so there’s nothing to push first.Heal is honest about what it finds. If a test is failing because your app genuinely broke, it reports a real bug rather than rewriting the test to go green.Healing a run with nothing failing returns No failing tests found in test run: <id>.

Watching and steering a run

checksum_session_status is what your agent polls. It reports overall progress, and includes the agent’s latest messages and file changes — so it can tell you what’s happening instead of “still running”.To redirect a run that’s already going, use checksum_session_prompt — the same as typing into the session in the web app. A session that already failed or was cancelled won’t accept a prompt, and you’ll get an error saying so.

Pulling reports and traces

checksum_test_run_download with a testRunId gives you the per-test results inline (what passed, what failed, and why) plus a link to the self-contained HTML report.To dig into one failing test, pass its testId as well — that returns its trace, screenshots and video. Those links are signed and expire, so they don’t stay live forever in a chat log.It lists your standard end-to-end runs; API-test runs and hidden runs don’t appear.

Working with several projects

If your account has access to more than one Checksum project, the tools that act on a single project need to know which one — otherwise you’ll see:

This credential is authorized for multiple applications: … Specify applicationId.

Just tell your agent which project you mean and it’ll pass the right id. Run checksum_whoami to see the list. An API key is always tied to exactly one project, so this never comes up there.

Connect with an API key

Browser sign-in needs a browser. For CI, a container, or a client that only speaks static tokens, use an API key instead. If browser sign-in worked, skip this. Grab the key from Settings → Project Settings in the web app (the same one the CLI and CI use), and send it as a bearer token:

Authorization: Bearer <YOUR_API_KEY>

Claude Code
Cursor
VS Code (Copilot)

claude mcp add --transport http checksum \
  https://api.checksum.ai/public-api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Your shell expands the value at the moment you run this, so the key is written into Claude Code’s config file as plain text. Treat that file as a secret — or use browser sign-in, which stores no key at all.

{
  "mcpServers": {
    "checksum": {
      "url": "https://api.checksum.ai/public-api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor has an open bug where ${env:VAR} inside headers is not substituted for remote servers — the literal text is sent as your token and you get an unexplained 401. Paste the key directly (and keep the file out of git), or use browser sign-in.

inputs makes VS Code prompt for the key once and store it securely, so it never sits in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "checksum-key",
      "description": "Checksum API Key",
      "password": true
    }
  ],
  "servers": {
    "checksum": {
      "type": "http",
      "url": "https://api.checksum.ai/public-api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:checksum-key}"
      }
    }
  }
}

An API key can start real cloud runs and open pull requests on your repo. Keep it out of any file you might commit, and prefer browser sign-in whenever you have a browser.

Troubleshooting

The tools don't show up

Most clients only read MCP config at startup — restart the client after editing mcp.json.Then ask your agent to run checksum_whoami. If that works, the connection is fine and the problem is your client’s tool list, not Checksum.

Everything returns 401 / Unauthorized

If you signed in through the browser, the session may have expired — reconnect from your client’s MCP settings.If you’re using an API key: check it’s sent as Authorization: Bearer <key>, and that it hasn’t been rotated in Settings → Project Settings.If you configured an API key earlier and are now trying browser sign-in, remove the old entry and its Authorization header first — a stale header wins over the browser session, and the client won’t fall back.

The approval page won't let me approve

It needs an active Checksum web-app session. Log in to app.checksum.ai in the same browser, then start the connection again.If you have no projects yet — or yours is still pending review — there’s nothing to authorize; finish project setup first.

It can't reach the server at all (timeouts, TLS errors, hangs)

On a corporate network or VPN, traffic to api.checksum.ai may be blocked or intercepted. Check you can reach it:

curl -I https://api.checksum.ai/public-api/mcp

If that hangs or fails, ask IT to allow api.checksum.ai over HTTPS (port 443). A TLS-inspecting proxy can also break the connection by re-signing certificates — it needs api.checksum.ai on its bypass list.Note that a proxy configured in your shell isn’t visible to a GUI app like Cursor or VS Code unless you launch it from that shell.

The agent generated tests for the wrong code

Checksum checks out your repository from the remote, so it only sees pushed commits. If your work is still local, commit and push, then ask again.

It generated tests but never opened a pull request

Checksum opens a PR only when it has the pull request number, the repository, and the branch. A run from a plain description produces tests in the session instead. Open a PR for your branch and ask again, referencing it.

It says my test run has no failing tests

Healing only operates on runs that actually failed. Ask your agent to list recent runs and pick one with failures.

My client asks for an SSE URL, or only supports local servers

Checksum speaks Streamable HTTP, not SSE — use the same URL and choose the HTTP transport.A client that can only launch local (stdio) servers can’t connect directly. Most such clients can be pointed at a remote server through a bridge, but the simplest path is to use one of the clients above.

Security

Your code is never uploaded from your machine. Checksum clones your repository from your connected Git provider, in the cloud. The MCP server only carries instructions and results.
Browser sign-in is scoped. You choose which projects a client may touch, and access is re-checked on every request. Revoke it any time from My Profile.
Report and trace links are signed and expire, so a URL pasted into a chat log doesn’t stay live forever.
Tools that cost money or open PRs are marked as such, so your client can ask before running them.

Next Steps

Coding Agent Integration — the local slash-command path (detect / generate / heal against your own repo)
Generate Tests — how generation works end to end
Auto-Healing — what healing does to a failing run
API Reference — the REST API behind the same capabilities

Getting Started

Test Creation

CLI & CI

Maintenance & Monitoring

Integrations

Security & SSO

Before you start

Connect your client

What you’re approving

Check that it worked

What you can ask

Tools

Connect with an API key

Troubleshooting

Security

Next Steps

​Before you start

​Connect your client

​What you’re approving

​Check that it worked

​What you can ask

​Tools

​Connect with an API key

​Troubleshooting

​Security

​Next Steps

Before you start

Connect your client

What you’re approving

Check that it worked

What you can ask

Tools

Connect with an API key

Troubleshooting

Security

Next Steps