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

# Coding Agents & MCP

> You can use Checksum from Claude Code, Cursor, VS Code, and other AI coding tools. Connect the hosted MCP server to trigger cloud generation, healing, and reports in plain English.

## At a glance

| Option | What it is | Best for |
| - | - | - |
| [MCP server](#mcp-server-connect-and-use) | A hosted server your coding agent connects to. The work runs in Checksum's cloud. | "Cover this PR", "detect the billing flows", "run the checkout tests", "heal that run", "why did it fail?" |

<div className="ai-ref">
  <Accordion title="Reference for AI: coding agents at a glance" icon="robot">
    | Item | Value |
    | - | - |
    | MCP server URL | `https://api.checksum.ai/public-api/mcp` (Streamable HTTP) |
    | MCP auth | Browser sign-in (recommended) or `Authorization: Bearer <YOUR_API_KEY>` ([API key](#mcp-connect-with-an-api-key)) |
    | Claude Code | `/plugin marketplace add checksum-ai/plugins` then `/plugin install checksum@checksum-ai`, or `claude mcp add --transport http checksum https://api.checksum.ai/public-api/mcp` |
    | Verify | Ask your agent: `Run checksum_whoami.` |
    | MCP tools (15) | Read-only: `checksum_whoami`, `checksum_session_status`, `checksum_session_list`, `checksum_test_run_list`, `checksum_test_run_download`. Changes things: `checksum_detect`, `checksum_test_generate`, `checksum_test_heal`, `checksum_test_run`, `checksum_session_prompt`, `checksum_session_approve`, `checksum_session_answer`, `checksum_session_stop`, `checksum_session_restart`, `checksum_session_create_pr` ([reference](#reference-for-ai-mcp-tools)) |

    * Push first: MCP runs in Checksum's cloud and only sees **pushed** commits.
    * PRs: a PR-based generate run (pull request number, repository, and branch) and a heal run open a PR by default. A run from a described flow, a detect session, or a targeted generate leaves its changes in the session: pass `autoCreatePR: true` up front, or call `checksum_session_create_pr` afterwards.
    * Deep mode: detect, generate, and heal run in Standard mode unless you pass `deepMode: true`. A deep-mode session pauses for plan approval (`checksum_session_approve`).
    * Several projects: tools that act on one project need an `applicationId`. Tell your agent which project you mean.
  </Accordion>
</div>

<div className="part dev"><span className="part-icon">{"</>"}</span><div><div className="part-title">Developer guide</div><div className="part-sub">Connect and use the cloud MCP server</div></div></div>

## MCP server: connect and use

Checksum runs a hosted [MCP](https://modelcontextprotocol.io) server, so any MCP-capable coding agent can drive Checksum directly. Connect once, then ask in plain English:

* *"Generate Checksum tests for this PR."*
* *"My checkout test is failing. Heal it."*
* *"Why did the last test run fail?"*
* *"Detect the flows in our billing area and generate tests for them."*

The work runs in Checksum's cloud and comes back as a pull request. There's no local test engine and no Playwright install.

<Note>
  **New to MCP?**

  MCP is a standard way for AI coding assistants to use outside tools. Once Checksum is connected over MCP, your assistant (Claude Code, Cursor, Copilot) can generate and fix tests for you when you ask. You don't need to understand the protocol. Connect once, then talk normally.
</Note>

```text theme={null}
https://api.checksum.ai/public-api/mcp
```

### Before you start

You need all three:

1. **A Checksum project that's set up**, with environment URL, test users, and Git connected. Checksum configures this during [onboarding](/docs/onboarding). Without a project, the MCP server has nothing to act on.
2. **An active login at [app.checksum.ai](https://app.checksum.ai)** in your browser. The approval screen needs it.
3. **An MCP-capable client**, such as Claude Code, Cursor, VS Code (Copilot), Claude desktop/web, or any other MCP client.

### Connect your client (browser sign-in)

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.

<Tabs>
  <Tab title="Claude Code">
    Install the Checksum plugin. It adds the connection **plus** skills that push your branch and find the right pull request before a cloud run:

    ```text Claude Code theme={null}
    /plugin marketplace add checksum-ai/plugins
    /plugin install checksum@checksum-ai
    ```

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

    <Accordion title="Just the server, without the plugin">
      ```bash theme={null}
      claude mcp add --transport http checksum https://api.checksum.ai/public-api/mcp
      ```

      Then run `/mcp` and pick **checksum** to sign in.
    </Accordion>
  </Tab>

  <Tab title="Cursor">
    Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` to enable it everywhere):

    ```json .cursor/mcp.json theme={null}
    {
      "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.
  </Tab>

  <Tab title="VS Code (Copilot)">
    Create `.vscode/mcp.json` in your project:

    ```json .vscode/mcp.json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Claude (web & desktop)">
    Go to **Customize → Connectors → Add custom connector** and paste:

    ```text theme={null}
    https://api.checksum.ai/public-api/mcp
    ```

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

    <Note>
      **Team & Enterprise plans**

      This setting is under **Organization settings → Connectors**, and only an Owner can add it.
    </Note>
  </Tab>

  <Tab title="Anything else">
    Any MCP client works. Point it at the server as a **Streamable HTTP** server:

    ```text theme={null}
    https://api.checksum.ai/public-api/mcp
    ```

    The server advertises browser sign-in, so a compliant client will offer to authenticate. For a client that can only send a static token, see [Connect with an API key](#mcp-connect-with-an-api-key).
  </Tab>
</Tabs>

### What you're approving

The browser shows which **projects** the client may act on. If you can access 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 does too.

Connections are reviewed and revoked in the web app ([Review or revoke MCP connections](#review-or-revoke-mcp-connections)).

### Check that it worked

Ask your agent, in plain English:

```text Prompt theme={null}
Run checksum_whoami.
```

It replies with the project you're connected to and a link to its dashboard. That one call tests the whole chain: client, connection, sign-in, and project access. If it doesn't work, see [Troubleshooting](#mcp-troubleshooting).

<Warning>
  **Push your work first**

  Checksum generates in the cloud by checking out your repo from your Git provider, so it only sees commits you've **pushed**. If you ask it to cover code that's still on your machine, it will test the old version. Commit and push, then ask. The Claude Code plugin does this for you.
</Warning>

### What you can ask

Once you're connected, talk to your agent normally. It picks the right tool.

| Goal | Example prompt |
| - | - |
| 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 first | `Why did the last Checksum run fail? Pull the report and show me the failing test.` |
| Steer a running session | `Tell the Checksum session to also cover the "expired card" case.` |
| Find flows worth testing | `Detect the user flows in the billing area and file them under the "Billing" collection.` |
| Generate from specs you already have | `Generate tests for every spec in the "Billing" collection and open a PR when it's done.` |
| Run tests and read the results | `Run the "Checkout" collection against https://preview-142.acme.dev and tell me what failed.` |
| Review a plan, or answer the agent | `Show me the plan the Checksum session is waiting on. Looks good — approve it.` |

<Note>
  **When a PR is opened**

  Checksum opens a pull request when it can. A **PR-based generate run** (one where it knows the pull request number, the repository, and the branch) and a **heal run** open one by default. A run from a flow you describe, a detect session, or a targeted generate leaves its changes in the session for review. Ask for a PR up front (`autoCreatePR`), or once you've reviewed it (`checksum_session_create_pr`).
</Note>

<div className="ai-ref">
  <Accordion title="Reference for AI: MCP server connection" icon="robot">
    | Setting | Value |
    | - | - |
    | Server URL | `https://api.checksum.ai/public-api/mcp` |
    | Transport | Streamable HTTP (not SSE) |
    | Auth | Browser sign-in (OAuth, recommended) or `Authorization: Bearer <YOUR_API_KEY>` header |

    | Client | Browser sign-in setup | Config location |
    | - | - | - |
    | Claude Code | `/plugin marketplace add checksum-ai/plugins` + `/plugin install checksum@checksum-ai`, or `claude mcp add --transport http checksum https://api.checksum.ai/public-api/mcp`; then `/mcp` → **checksum** → approve | Claude Code MCP config |
    | Cursor | `{"mcpServers": {"checksum": {"url": "https://api.checksum.ai/public-api/mcp"}}}`; restart; **Customize** → MCP → **checksum** → sign in | `.cursor/mcp.json` or `~/.cursor/mcp.json` |
    | VS Code (Copilot) | `{"servers": {"checksum": {"type": "http", "url": "https://api.checksum.ai/public-api/mcp"}}}`; click **Start**; approve | `.vscode/mcp.json` |
    | Claude web & desktop | **Customize → Connectors → Add custom connector** (Team/Enterprise: **Organization settings → Connectors**, Owner only) | n/a |
    | Other MCP clients | Add as a Streamable HTTP server. The server advertises browser sign-in. | Client-specific |

    * Prerequisites: a Checksum project (set up during onboarding), an active login at `https://app.checksum.ai` in the same browser, and an MCP-capable client.
    * Approval scope: per project. Access is re-checked on every request. Connections belong to the user and are revoked from **My Profile → MCP connections**.
    * Verification: the prompt `Run checksum_whoami.` returns the connected project and a dashboard link.
    * A PR opens by default for PR-based generate runs (PR number + repository + branch known) and heal runs. Other runs open one with `autoCreatePR: true` or `checksum_session_create_pr`.
  </Accordion>
</div>

## What your agent can do

You don't need to name tools yourself. Ask for what you want and your agent picks the right one. Behind the scenes, the Checksum MCP server gives your agent these abilities:

* **Check the connection** and see which projects you can use.
* **Detect flows** worth testing in your app (and optionally its code), written up as test specs.
* **Generate tests** for a pull request, for a flow you describe, or for specs you already have.
* **Run tests**: the whole suite, a collection, specific tests, or tests matching a pattern.
* **Heal a failed run**, opening a pull request with the fixes.
* **Follow a run as it happens**, including what the agent is doing, which files it changed, and the PR it opened, and **steer it** with follow-up instructions.
* **Approve a plan or answer a question** a session is waiting on, so a session started from your editor never has to wait on the web app.
* **Stop, restart, or open a PR** for a session.
* **Find recent test runs and sessions**, and **pull results**, the HTML report, and a failing test's trace, screenshots, and video.

Anything that starts a cloud run or opens a pull request is marked as such, so a good client asks you to confirm first. Every result includes links into the Checksum web app, so you can open a session or run directly instead of working with IDs.

Healing doesn't hide real problems: if a test fails because your app is broken, it reports a **real bug** instead of rewriting the test to pass. Report and trace links are signed and expire, so they don't stay live forever in a chat log.

### Deep mode and the approval loop

Detect, generate, and heal run in **Standard** mode by default: fully autonomous, start to finish. Pass `deepMode: true` for [Deep mode](/docs/generation-modes): slower, more thorough, and it pauses after planning for your approval. Over MCP that loop is explicit:

1. Poll `checksum_session_status` until `nextAction` is `"approve"`.
2. Read `planMd`, the plan awaiting approval. `planMdTruncated` tells you if it was cut short; the full plan is in the web app.
3. Call `checksum_session_approve` to continue into implementation. To ask for changes instead, send them with `checksum_session_prompt`. A prompt during approval reopens the planning step; it does **not** approve it. Poll again for the revised plan.

Questions work the same way. When `nextAction` is `"answer"`, read `pendingQuestions` and call `checksum_session_answer` with `answers`: one array per sub-question of the first pending group, in order, each holding the selected option **labels** (exactly one unless the sub-question allows multiple; free text is accepted when no option fits). For example, for two sub-questions: `[["Playwright"], ["Login", "Checkout"]]`. Pass `questionId` to address a specific group when more than one is pending.

<Note>
  **Approval is a deliberate gate**

  There's no auto-approve flag. If nobody will be around to review the plan, leave deep mode off.
</Note>

### Typical flows

**Detect flows, then generate tests for them.** Ask: *"Detect the user flows in the billing area, then generate tests for them and open a PR."* Your agent calls `checksum_detect` with `collectionNames: ["Billing"]`, polls `checksum_session_status` by `sessionId` until `nextAction` is `"done"`, then calls `checksum_test_generate` with the same `collectionNames` (or the `userStoryIds` it detected) and `autoCreatePR: true`.

**Start a run and read the results.** Ask: *"Run the Checkout collection against the preview deployment and tell me what failed."* Your agent calls `checksum_test_run` (`mode: "collection"`), waits for the run to finish via `checksum_test_run_list`, then calls `checksum_test_run_download`, with a `testId` for the trace and screenshots of a failing test.

**Heal a failing run and open the PR.** Ask: *"Heal the failures in the last Checksum run."* Your agent calls `checksum_test_heal` with the `testRunId`, polls `checksum_session_status` by `batchId` until it's done, and hands you the `prUrl`. If a session finished without a PR, it calls `checksum_session_create_pr`.

### Working with several projects (`applicationId`)

If your account can access more than one Checksum project, the tools that act on a single project need to know which one. Otherwise you'll see:

```text theme={null}
This credential is authorized for multiple applications: … Specify applicationId.
```

Tell your agent which project you mean, and it will pass the right ID. Run `checksum_whoami` to see the list. An API key is always tied to exactly one project, so this doesn't happen with API keys.

<div className="ai-ref">
  <Accordion title="Reference for AI: MCP tools" icon="robot">
    | Tool | What it does | Type |
    | - | - | - |
    | [`checksum_whoami`](#checksum_whoami-check-the-connection) | Confirms your connection and lists the projects you're authorized for. | Read-only |
    | [`checksum_detect`](#checksum_detect-discover-flows-to-test) | Starts a detection session that explores your app (and optionally its code) to discover user flows and write them up as test specs. Returns a `sessionId`. | **Changes things** |
    | [`checksum_test_generate`](#checksum_test_generate-start-test-generation) | Starts a test-generation run: for a pull request, for a flow you describe, or for existing specs (`userStoryIds` / `collectionNames`). Returns a `batchId`, or a `sessionId` for a targeted run. | **Changes things** |
    | [`checksum_test_heal`](#checksum_test_heal-heal-a-failed-run) | Starts an auto-heal run for the failing tests in a test run. Returns a `batchId`. | **Changes things** |
    | [`checksum_test_run`](#checksum_test_run-start-a-test-run) | Starts a test run: the whole suite, a collection, specific tests, or tests matching a pattern. Returns the `testRunId`. | **Changes things** |
    | [`checksum_test_run_list`](#checksum_test_run_list-list-test-runs) | Lists recent test runs, newest first, so the agent can find a failing run without you hunting for an ID. | Read-only |
    | [`checksum_test_run_download`](#checksum_test_run_download-pull-results-reports-and-traces) | Returns 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. | Read-only |
    | [`checksum_session_list`](#checksum_session_list-list-sessions) | Lists recent agent sessions. | Read-only |
    | [`checksum_session_status`](#checksum_session_status-watch-a-run) | Reports a run's progress, what the agent is doing, the files it changed, the `prUrl` it opened, and `nextAction`, the tool to call next. Your agent polls it until the run finishes. | Read-only |
    | [`checksum_session_prompt`](#checksum_session_prompt-steer-a-session) | Sends a follow-up instruction into a session. Use it to steer an agent mid-run, or resume a stopped one. | **Changes things** |
    | [`checksum_session_approve`](#checksum_session_approve-approve-a-plan) | Approves the plan a deep-mode session is waiting on, so it continues into implementation. | **Changes things** |
    | [`checksum_session_answer`](#checksum_session_answer-answer-the-agent) | Answers the question(s) a session is waiting on. | **Changes things** |
    | [`checksum_session_stop`](#checksum_session_stop-and-checksum_session_restart) | Stops (pauses) a running session. It keeps its workspace, so you can resume it with a prompt or restart it. | **Changes things** |
    | [`checksum_session_restart`](#checksum_session_stop-and-checksum_session_restart) | Restarts a stopped, failed, or finished session from the beginning as a **new** session. Poll the returned ID from then on. | **Changes things** |
    | [`checksum_session_create_pr`](#checksum_session_create_pr-open-the-pull-request) | Opens the pull request for a completed session that hasn't opened one yet. Returns the existing `prUrl` if it already has one. | **Changes things** |

    Tools marked "Changes things" start billable cloud runs and sessions, steer them, and can open pull requests. Clients should confirm before calling them.

    #### `checksum_whoami`: check the connection

    | Type | Returns |
    | - | - |
    | Read-only | The project you're connected to, a link to its dashboard, and the projects you're authorized for |

    One call tests the whole chain: client, connection, sign-in, and project access. Run it first when anything looks wrong, and to see the project list when you work with several projects.

    #### `checksum_detect`: discover flows to test

    | Input | Required | Description |
    | - | - | - |
    | `instructions` | Yes | Which areas to explore, what to skip, how to log in |
    | `collectionNames` | No | Collections to file the detected specs under |
    | `codeRepoNames` | No | Connected code repositories the agent may also read |
    | `deepMode` | No | `true` for [Deep mode](#deep-mode-and-the-approval-loop). Default: Standard |
    | `autoCreatePR` | No | `true` to open a pull request with the specs when the session finishes |

    **Type:** changes things. **Returns:** a `sessionId`. Poll `checksum_session_status` with it. When the session finishes, the specs are ready for `checksum_test_generate` (by collection or by `userStoryIds`), and `autoCreatePR` or `checksum_session_create_pr` puts them in a pull request. See also [Detect Test Flows](/docs/detect-tests).

    #### `checksum_test_generate`: start test generation

    Give it **one** of three inputs: a pull request, a description, or specs you already have.

    | Input | Required | Description |
    | - | - | - |
    | Pull request number, repository, and branch | All three together, **or** one of the options below | Generates tests for that pull request and opens a **pull request** with them. |
    | `extraInstructions` | Instead of a PR | Describes the flow to cover. The tests stay in the session for you to review first. |
    | `userStoryIds` and/or `collectionNames` | Instead of a PR | **Targeted generation**: generates tests for exactly those specs, for example the flows `checksum_detect` just found. Can't be combined with a pull request. Returns a `sessionId` instead of a `batchId`. |
    | `codeRepoNames`, `repoBranches` | No (targeted runs) | Which connected code repositories (and branches) the agent reads |
    | `autoCreatePR` | No | `true` to open a pull request when a description or targeted run finishes |
    | `deepMode` | No | `true` for [Deep mode](#deep-mode-and-the-approval-loop). Default: Standard |
    | `envOverrides` | No | Points the run at a different environment, such as a preview deployment |

    **Type:** changes things. **Returns:** a `batchId` (a `sessionId` for a targeted run). Asking twice for the same pull request won't start a second run. The request joins the run already in progress. Push your commits first, because cloud generation only sees pushed code. See also [Generate Tests](/docs/generate-tests).

    #### `checksum_test_heal`: heal a failed run

    | Input | Required | Description |
    | - | - | - |
    | `testRunId` | Yes | A test run that **has failures**. If you don't have one, ask your agent to list recent runs ([`checksum_test_run_list`](#checksum_test_run_list-list-test-runs)). |

    **Type:** changes things. **Returns:** a `batchId`. 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 has already finished, so there's nothing to push first.

    Healing doesn't hide real problems. If a test fails because your app is broken, it reports a **real bug** instead of rewriting the test to pass. Healing a run with nothing to heal returns the reason:

    ```text theme={null}
    No tests to heal in test run: <id> — <reason>
    ```

    Pass `deepMode: true` for [Deep mode](#deep-mode-and-the-approval-loop). See also [Auto-Healing](/docs/auto-healing).

    #### `checksum_test_run`: start a test run

    | Input | Required | Description |
    | - | - | - |
    | `mode` | Yes | `suite` (everything), `collection` (takes `collectionId`), `tests` (takes `testIds`), or `grep` (matches a pattern against test names) |
    | `envOverrides` | No (`grep`) | Runs against a preview deployment or other environment |
    | `environmentNameOverride`, `environmentUserRoleOverride` | No (`collection`, `tests`) | Picks an environment and user role from your `checksum.config.ts` |
    | `shardCount` | No | Fans the run out across parallel shards |
    | `autoHeal` | No | `true` starts healing sessions for the failing tests when the run finishes. Works with `shardCount`. Those sessions don't open a pull request on their own: call `checksum_session_create_pr` when one completes. |

    **Type:** changes things. **Returns:** the `testRunId`. Read the results with `checksum_test_run_download` once `checksum_test_run_list` shows the run finished. See also [Running Tests](/docs/running-tests).

    #### `checksum_session_status`: watch a run

    **Type:** read-only. Your agent polls it until the run finishes. It reports overall progress, the agent's latest messages, the files it changed, and the `prUrl` it opened. That lets your agent tell you what's happening instead of just "still running."

    Poll by `batchId` for a generate or heal run, or by `sessionId` alone for a detect or targeted-generate session.

    | Field | Meaning |
    | - | - |
    | `nextAction` | The tool to call next: `approve`, `answer`, `prompt`, `wait`, `done`, or `failed` |
    | `planMd` | The plan awaiting approval (deep mode). `planMdTruncated` is `true` if it was cut short; the full plan is in the web app |
    | `pendingQuestions` | The question groups the session is waiting on, with their options |
    | `prUrl` | The pull request the session opened, once it has one |

    #### `checksum_session_prompt`: steer a session

    **Type:** changes things. Sends a follow-up instruction into a session, the same as typing into the session in the web app. It works on running, waiting, paused, and completed sessions, and resumes a stopped one. A session that was cancelled, or failed without a way back, won't accept a prompt, and you'll get an error saying so. During plan approval, a prompt reopens planning instead of approving.

    #### `checksum_session_approve`: approve a plan

    **Type:** changes things. Approves the plan a deep-mode session is waiting on (`nextAction` is `approve`), so it continues into implementation. See [Deep mode and the approval loop](#deep-mode-and-the-approval-loop).

    #### `checksum_session_answer`: answer the agent

    | Input | Required | Description |
    | - | - | - |
    | `answers` | Yes | One array per sub-question of the first pending group, in order, each holding the selected option **labels**. Exactly one label unless the sub-question allows multiple; free text is accepted when no option fits. Example: `[["Playwright"], ["Login", "Checkout"]]` |
    | `questionId` | No | Addresses a specific question group when more than one is pending |

    **Type:** changes things. Use it when `nextAction` is `answer`.

    #### `checksum_session_stop` and `checksum_session_restart`

    **Type:** changes things. `checksum_session_stop` pauses a session and keeps its workspace. Resume it with `checksum_session_prompt`, or start over with `checksum_session_restart`. A restart is a **new** session (the original is kept as a record), so poll the returned `restartedAiAgentsSessionId` from then on. Restart works on stopped, failed, and finished sessions.

    #### `checksum_session_create_pr`: open the pull request

    **Type:** changes things. Opens the pull request for a completed session that hasn't opened one yet, and returns the existing `prUrl` if it already has one. The call is synchronous and can take a minute or two. If it times out, poll `checksum_session_status` for the `prUrl` or call it again.

    #### `checksum_session_list`: list sessions

    **Type:** read-only. Lists recent agent sessions.

    #### `checksum_test_run_list`: list test runs

    **Type:** read-only. Lists recent test runs, newest first, so the agent can find a failing run (for example, a `testRunId` for `checksum_test_heal`) without you hunting for an ID.

    #### `checksum_test_run_download`: pull results, reports, and traces

    | Input | Required | Returns |
    | - | - | - |
    | `testRunId` | Yes | The per-test results inline (what passed, what failed, and why) plus a link to the self-contained HTML report |
    | `testId` | No | Also returns that test's trace, screenshots, and video |

    **Type:** read-only. Report and trace 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.
  </Accordion>
</div>

## MCP: connect with an API key

Browser sign-in needs a browser. For CI, a container, or a client that only supports static tokens, use an API key instead. **If browser sign-in worked, skip this.**

Get the key from **Settings → Project Settings** in the web app. It's the same key the CLI and CI use (see [API Keys](/docs/authentication#your-api-key)). Send it as a bearer token:

```text theme={null}
Authorization: Bearer <YOUR_API_KEY>
```

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http checksum \
      https://api.checksum.ai/public-api/mcp \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    <Warning>
      **Key stored in plain text**

      Your shell expands the value when 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.
    </Warning>
  </Tab>

  <Tab title="Cursor">
    ```json .cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "checksum": {
          "url": "https://api.checksum.ai/public-api/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Warning>
      **Known Cursor bug**

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

  <Tab title="VS Code (Copilot)">
    `inputs` makes VS Code prompt for the key once and store it securely, so the key never appears in the file:

    ```json .vscode/mcp.json theme={null}
    {
      "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}"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  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 use browser sign-in whenever you have a browser.
</Warning>

## MCP troubleshooting

<AccordionGroup>
  <Accordion title="The tools don't show up">
    Most clients only read MCP config at startup, so 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.
  </Accordion>

  <Accordion title="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 that it's sent as `Authorization: Bearer <key>` and that it hasn't been rotated in **Settings → Project Settings**.

    If you set up an API key earlier and are now switching to browser sign-in, **remove the old entry and its `Authorization` header first**. A stale header takes precedence over the browser session, and the client won't fall back.
  </Accordion>

  <Accordion title="The approval page won't let me approve">
    Approval needs an active Checksum web-app session. Log in to [app.checksum.ai](https://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. Your Checksum team sets up the project during [onboarding](/docs/onboarding).
  </Accordion>

  <Accordion title="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 that you can reach it:

    ```bash theme={null}
    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. See [Network access](/docs/security-and-access#network-access).

    A proxy configured in your shell isn't visible to a GUI app like Cursor or VS Code unless you launch the app from that shell.
  </Accordion>

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

  <Accordion title="It generated tests but never opened a pull request">
    Checksum opens a PR by default only when it has the pull request number, the repository, and the branch. A run from a plain description, a detect session, or a targeted generate leaves its changes in the session. Ask your agent to open one with `checksum_session_create_pr`, or pass `autoCreatePR: true` next time.
  </Accordion>

  <Accordion title="It says my test run has no tests to heal">
    Healing only works on runs that actually failed, and the message says why this one was skipped. Ask your agent to list recent runs and pick one with failures.
  </Accordion>

  <Accordion title="The session is stuck waiting">
    Ask your agent to check `checksum_session_status`. If `nextAction` is `approve`, the session is a deep-mode run waiting on its plan: approve it with `checksum_session_approve`. If it's `answer`, answer the pending question with `checksum_session_answer`. See [Deep mode and the approval loop](#deep-mode-and-the-approval-loop).
  </Accordion>

  <Accordion title="My client asks for an SSE URL, or only supports local servers">
    Checksum uses **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 reach a remote server through a bridge, but the simplest option is to use a supported client: Claude Code, Cursor, VS Code (Copilot), or Claude web and desktop ([Connect your client](#connect-your-client-browser-sign-in)).
  </Accordion>
</AccordionGroup>

<div className="part ui"><span className="part-icon">▦</span><div><div className="part-title">In the Checksum web app</div><div className="part-sub">Review and revoke MCP connections</div></div></div>

## Review or revoke MCP connections

Review or revoke a connection any time from the **MCP connections** card on **My Profile** in the web app. A connection belongs to *you*, not to a project, so revoking it cuts the client off from every project you granted.

If you connect with an API key instead, the key lives in **Settings → Project Settings** (see [API keys](/docs/authentication#your-api-key)).

<div className="part bg"><span className="part-icon">i</span><div><div className="part-title">How it works</div><div className="part-sub">MCP security and related pages</div></div></div>

## MCP 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, steer sessions, or open PRs are marked as such**, so your client can ask before running them.

## Related

<CardGroup cols={2}>
  <Card title="Generate Tests" icon="wand-magic-sparkles" href="/docs/generate-tests">
    Every generation trigger, including MCP.
  </Card>

  <Card title="Auto-Healing" icon="bolt" href="/docs/auto-healing">
    What healing does to a failing run.
  </Card>

  <Card title="API Keys & Authentication" icon="key" href="/docs/authentication">
    Where the key comes from and how to keep it safe.
  </Card>

  <Card title="CI Setup Prompts" icon="robot" href="/docs/ci-setup-prompts">
    Prompts that have your agent build Checksum GitHub Actions workflows.
  </Card>
</CardGroup>