# Connect an AI agent over MCP

URL: https://testmode.ai/docs/mcp-server/

> Connect Claude, ChatGPT, Cursor, VS Code or Claude Code to Testmode's MCP server at api.testmode.ai/mcp, by signing in or with an API key. The tools it offers and what an agent can and can't do.

Testmode's **MCP server** lets AI agents use Testmode: list your projects and test cases, start runs and read the results. An AI coding agent can then run the tests for the change it just made and tell you what failed.

The server is at `https://api.testmode.ai/mcp`. Connect it in one of two ways:

| Sign in as you (OAuth) | A project API key |
| --- | --- |
| The agent acts as you, in every project you belong to, with your role | The agent works in one project, as the key's creator with less rights |
| Approve the app once in your browser | Paste the key into the app's configuration |
| Disconnect any time from your profile | Revoke the key on **API & CI** |
| For apps that support it: claude.ai, ChatGPT, Claude Code | For any MCP client, and for unattended agents |

## Claude, ChatGPT and other apps that take a URL

1. In the app, add a custom connector (or MCP server) with the URL `https://api.testmode.ai/mcp`.

2. The app opens Testmode's sign-in page. Sign in.

3. Testmode shows which app wants access, the address it will be sent to, and what it will be able to do. Click to approve.

The app's website, as it registered itself, is shown as plain text marked not verified: anyone can register an app, so check the name and the address before approving.

## Claude Code

```bash
claude mcp add --transport http testmode https://api.testmode.ai/mcp
```

Claude Code signs in through your browser the first time. To use a key instead:

```bash
claude mcp add --transport http testmode https://api.testmode.ai/mcp \
  --header "Authorization: Bearer $TESTMODE_API_KEY"
```

## Cursor, VS Code and other JSON configs

```json
{
  "mcpServers": {
    "testmode": {
      "url": "https://api.testmode.ai/mcp",
      "headers": { "Authorization": "Bearer tmk_…" }
    }
  }
}
```

Leave out `headers` to sign in through the browser instead, where the client supports it. **Settings** > **API & CI** > **MCP** shows these snippets for your project.

## Tools

| Tool | Does |
| --- | --- |
| `list_projects` | The projects the agent can use, with your role in each |
| `get_project` | A project's environments and test plans |
| `list_test_cases` | Test cases, filtered by tag or name |
| `start_run` | Starts a run of a plan, test case ids or tags |
| `get_run` | A run's status and each test's result and summary |
| `list_runs` | Recent runs |

Signed in, tools take an optional `project` (name or id). Runs take a few minutes, so agents start one and poll `get_run` until it is finished.

## What an agent can and can't do

- **It can** read projects, environments, test plans, test cases and runs, and start runs where you are an Editor or above.
- **It can't** change or delete tests, plans or settings, read credentials or variable values, or create API keys.
- **Its runs count** against your test runs like any other, and show `(MCP)` with the app's name as their trigger.
- **Test summaries may quote your site's text.** Agents should treat them as data, not instructions; Testmode tells them so.

## Disconnect an app

Open **Profile** > **Connected apps** and click **Disconnect** next to the app. Its next request fails. See [Your profile](https://testmode.ai/docs/your-profile/).

## Related

- [Run tests from CI and AI agents](https://testmode.ai/docs/api-ci-mcp/): All the ways in, side by side.
- [API keys](https://testmode.ai/docs/api-keys/): For clients that use a key.
- [Roles and permissions](https://testmode.ai/docs/roles-and-permissions/): What your role lets an agent do.