---
title: "MCP Server"
sidebarTitle: "MCP Server"
description: "Install the TestDriver MCP server in any AI client — Claude Code, Cursor, VS Code, Windsurf, Codex, Zed, and more"
icon: "plug"
---

## Overview

The **TestDriver MCP server** exposes TestDriver's computer-use tools — `session_start`, `find`, `click`, `type`, `assert`, `check`, `screenshot`, and more — over the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP-capable AI client can use it to drive a live sandbox and write real end-to-end tests.

It runs as a local stdio process:

```bash
npx -p testdriverai testdriverai-mcp
```

and authenticates with your `TD_API_KEY` (from [console.testdriver.ai/team](https://console.testdriver.ai/team)).

## Quick install (recommended)

`testdriverai init` wires up the MCP server, the [agent](/v7/ai/agent), and the [skills](/v7/ai/skills) for you, writing each client's config in the exact format and location it expects:

```bash
# interactive — pick your client(s)
npx testdriverai init

# one client
npx testdriverai init --client claude-code

# several
npx testdriverai init --client claude-code,cursor,vscode

# everything
npx testdriverai init --client all
```

<Info>
`init` detects clients already present in your project and pre-selects them in the picker. Re-running `init` is safe — it merges the TestDriver entry into existing config without overwriting your other servers.
</Info>

## Client support matrix

| Client | Auto-install | MCP config file | Config key |
| --- | --- | --- | --- |
| Claude Code | ✅ | `.mcp.json` | `mcpServers` |
| Claude Desktop | ✅ | OS-specific (see below) | `mcpServers` |
| Cursor | ✅ | `.cursor/mcp.json` | `mcpServers` |
| VS Code (Copilot) | ✅ | `.vscode/mcp.json` | `servers` |
| Windsurf | ✅ | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` |
| Codex | ✅ | `~/.codex/config.toml` | `[mcp_servers]` |
| Zed | ✅ | `.zed/settings.json` | `context_servers` |
| Lovable | ⚙️ partial | GitHub `AGENTS.md` + UI | — |
| Replit | ⚙️ partial | `replit.md` + UI | — |
| v0 (Vercel) | 📝 manual | web UI only | — |

<Note>
Each client uses a **different top-level key** for MCP servers. The most common mistake when configuring by hand is using `mcpServers` for VS Code (it wants `servers`), Codex (TOML `[mcp_servers]`), or Zed (`context_servers`).
</Note>

## Manual installation

If you'd rather configure by hand, use the snippets below. The stdio command is the same everywhere; only the wrapper key and file location change.

<Tabs>
  <Tab title="Claude Code">
    Add to `.mcp.json` at your project root (or `~/.claude.json` for all projects):

    ```json
    {
      "mcpServers": {
        "testdriver": {
          "type": "stdio",
          "command": "npx",
          "args": ["-p", "testdriverai", "testdriverai-mcp"],
          "env": { "TD_API_KEY": "${TD_API_KEY}" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Edit the Claude Desktop config file:

    - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
    - **Linux:** `~/.config/Claude/claude_desktop_config.json`

    ```json
    {
      "mcpServers": {
        "testdriver": {
          "command": "npx",
          "args": ["-p", "testdriverai", "testdriverai-mcp"],
          "env": { "TD_API_KEY": "your_api_key" }
        }
      }
    }
    ```

    Restart Claude Desktop after saving.
  </Tab>

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

    ```json
    {
      "mcpServers": {
        "testdriver": {
          "type": "stdio",
          "command": "npx",
          "args": ["-p", "testdriverai", "testdriverai-mcp"],
          "env": { "TD_API_KEY": "${TD_API_KEY}" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json`. VS Code uses the `servers` key and an `inputs` prompt for secrets:

    ```json
    {
      "servers": {
        "testdriver": {
          "type": "stdio",
          "command": "npx",
          "args": ["-p", "testdriverai", "testdriverai-mcp"],
          "env": { "TD_API_KEY": "${input:testdriver-api-key}" }
        }
      },
      "inputs": [
        {
          "type": "promptString",
          "id": "testdriver-api-key",
          "description": "TestDriver API Key From https://console.testdriver.ai/team",
          "password": true
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Windsurf reads MCP config globally. Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json
    {
      "mcpServers": {
        "testdriver": {
          "command": "npx",
          "args": ["-p", "testdriverai", "testdriverai-mcp"],
          "env": { "TD_API_KEY": "${TD_API_KEY}" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    Codex uses TOML. Add to `~/.codex/config.toml`:

    ```toml
    [mcp_servers.testdriver]
    command = "npx"
    args = ["-p", "testdriverai", "testdriverai-mcp"]
    env = { TD_API_KEY = "${TD_API_KEY}" }
    ```
  </Tab>

  <Tab title="Zed">
    Zed calls them "context servers". Add to `.zed/settings.json` (project) or `~/.config/zed/settings.json` (global):

    ```json
    {
      "context_servers": {
        "testdriver": {
          "command": "npx",
          "args": ["-p", "testdriverai", "testdriverai-mcp"],
          "env": { "TD_API_KEY": "${TD_API_KEY}" }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Web-based clients

Lovable, Replit, and v0 run in the browser, so the MCP server can't be launched as a local process. Configure them through each product's UI.

<AccordionGroup>
  <Accordion title="Lovable">
    1. Connect your GitHub repo and run `npx testdriverai init --client lovable` — this writes `AGENTS.md` and the skills into the repo so Lovable's agent picks them up.
    2. In Lovable, open **Settings → MCP** and add the TestDriver server.
  </Accordion>

  <Accordion title="Replit">
    1. Run `npx testdriverai init --client replit` to write `replit.md` with the TestDriver agent guidance.
    2. In Replit, open **Tools → Integrations → MCP** and add a custom MCP server.
  </Accordion>

  <Accordion title="v0 (Vercel)">
    v0 is fully UI-driven and does not read repo files.

    1. Open **[v0.app/chat/settings/mcp-connections](https://v0.app/chat/settings/mcp-connections)** and add the TestDriver MCP connection.
    2. Paste the agent guidance into **Instructions** (the **+** in the prompt bar).
  </Accordion>
</AccordionGroup>

## Verifying the install

After installing, open your client's chat and ask the agent to write a test:

```text
@testdriver write a test that opens the homepage and asserts the title
```

If the MCP server is wired up correctly, the agent will start a session and you'll see screenshots come back as it works. If tools don't appear, check that `TD_API_KEY` is set and restart the client.

## Related

- [Agent](/v7/ai/agent) — the test-creator that uses these tools
- [Skills](/v7/ai/skills) — instruction files describing each tool
- [CI/CD](/v7/ci-cd) — running the generated tests in your pipeline
