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

# MCP Setup

> Connect any AI client to TestDriver by adding one URL.

TestDriver runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server. There is nothing to install and no API key to paste. Add one URL to your AI client, sign in through the browser, and the computer-use tools appear in chat.

```text theme={null}
https://mcp.testdriver.ai/mcp
```

<Info>
  **Prerequisites**

  * An MCP-compatible AI client (Claude, Claude Code, VS Code, Cursor, ChatGPT, and others)
  * A TestDriver account. [Create one for free](https://console.testdriver.ai/settings). You get 60 device minutes, no credit card required.
</Info>

## Add the server

Most clients accept the URL directly. Pick yours below.

<Tabs>
  <Tab title="Claude">
    1. Open **Settings → Connectors → Add custom connector**.
    2. Paste `https://mcp.testdriver.ai/mcp`.
    3. Click **Connect** and sign in with TestDriver when the browser opens.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http testdriver https://mcp.testdriver.ai/mcp
    ```

    Run `/mcp` in a session to start the browser login and confirm the tools are connected.
  </Tab>

  <Tab title="VS Code">
    Add this to `.vscode/mcp.json` in your project. VS Code uses the `servers` key:

    ```json .vscode/mcp.json theme={null}
    {
      "servers": {
        "testdriver": {
          "type": "http",
          "url": "https://mcp.testdriver.ai/mcp"
        }
      }
    }
    ```

    VS Code prompts you to authorize the server the first time you use it.
  </Tab>

  <Tab title="Cursor">
    Add this to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

    ```json .cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "testdriver": {
          "url": "https://mcp.testdriver.ai/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="ChatGPT">
    1. Open **Settings → Connectors → Create**.
    2. Paste `https://mcp.testdriver.ai/mcp` as the MCP server URL.
    3. Choose OAuth for authentication and sign in with TestDriver.
  </Tab>

  <Tab title="Other clients">
    Any spec-compliant client works. Point it at the URL using the streamable HTTP transport:

    ```json theme={null}
    {
      "mcpServers": {
        "testdriver": {
          "url": "https://mcp.testdriver.ai/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  Clients disagree on the top-level key. VS Code uses `servers`, most others use `mcpServers`, Zed uses `context_servers`, and Codex uses TOML `[mcp_servers]`. If the tools do not show up, check the key before anything else.
</Note>

## Sign in

The server speaks OAuth 2.1 and advertises its authorization server via [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected-resource metadata:

```text theme={null}
https://mcp.testdriver.ai/.well-known/oauth-protected-resource
```

Spec-compliant clients read that metadata, open a browser, and complete the handshake for you. Every tool is scoped to the team you sign in with.

## Verify it works

Ask your client to drive a browser:

```text theme={null}
Use TestDriver to open example.com and assert the page title is visible.
```

The agent starts a sandbox and returns a screenshot with every action. Each connection gets its own isolated sandbox, so multiple people and multiple chats can run tests at the same time without interfering.

## What you get

The hosted server exposes the full live tool set:

| Tool | Purpose |
| - | - |
| `session_start`, `session_status`, `session_extend` | Start a sandbox, check its health, add more time |
| `find`, `findall`, `find_and_click` | Locate elements by plain-English description |
| `click`, `hover`, `type`, `press_keys`, `scroll` | Perform actions |
| `assert`, `check` | Ask yes/no questions about the screen |
| `screenshot`, `exec`, `wait`, `focus_application` | Capture state, run commands, pause |

Every action also returns the SDK code for that step, so the agent can write a runnable [Vitest](https://vitest.dev) test as it goes.

## Local server for CI and automation

For headless automation, or when you would rather use an API key than a browser login, run the server as a local stdio process:

```bash theme={null}
npx -p testdriverai testdriverai-mcp
```

It reads `TD_API_KEY` from the environment. Generate a key at [console.testdriver.ai/settings](https://console.testdriver.ai/settings).

```json theme={null}
{
  "mcpServers": {
    "testdriver": {
      "type": "stdio",
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${TD_API_KEY}" }
    }
  }
}
```

<Tip>
  `npx testdriverai init` writes this config for you, plus the TestDriver agent, skills, an example test, and a GitHub Actions workflow. See [Setting up your workspace](/quickstart-manual).
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The tools do not appear in my client">
    Confirm the URL is exactly `https://mcp.testdriver.ai/mcp`, check that you used the correct top-level config key for your client, and restart the client. Most clients read their MCP config only at startup.
  </Accordion>

  <Accordion title="The browser login never completes">
    Your client must support OAuth 2.1 with Dynamic Client Registration. Older clients, and clients that only support stdio servers, cannot connect to the hosted URL. Use the local server with `TD_API_KEY` instead.
  </Accordion>

  <Accordion title="I ran out of device minutes">
    Sandbox time is billed per minute. Check your usage and plan at [console.testdriver.ai](https://console.testdriver.ai).
  </Accordion>

  <Accordion title="The sandbox expired mid-session">
    Sessions time out after a period of inactivity. Ask the agent to call `session_extend` before it expires, or `session_start` to get a fresh sandbox.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Generating tests" icon="wand-magic-sparkles" href="/generating-tests" arrow horizontal>
    Prompting patterns that get the best tests out of the agent.
  </Card>

  <Card title="Setting up your workspace" icon="wrench" href="/quickstart-manual" arrow horizontal>
    Add the SDK to a project so generated tests run locally and in CI.
  </Card>

  <Card title="Walkthrough" icon="map" href="/provision" arrow horizontal>
    Provision apps, locate elements, perform actions, and make assertions.
  </Card>

  <Card title="CI/CD" icon="circle-play" href="/ci-cd" arrow horizontal>
    Run your tests on every pull request.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.