Testdriver Claude Mcp Plugin

---
name: testdriver:claude-mcp-plugin
description: claude-mcp-plugin
---
<!-- Generated from claude-mcp-plugin.mdx. DO NOT EDIT. -->

TestDriver ships as a native [Claude Code plugin](https://docs.claude.com/en/docs/claude-code/plugins) that bundles the **TestDriver MCP server**, the **`testdriver` expert sub-agent**, and all **TestDriver skills**. You get everything you need to drive TestDriver from Claude Code with a single install.

> The plugin lives inside the `testdriverai` npm package at `ai/.claude-plugin/plugin.json`, and the marketplace entry lives at `.claude-plugin/marketplace.json` in this repo.

## 1. Get a TestDriver API key

- Visit your team page (e.g. `https://console.testdriver.ai/settings`)
- Create or copy a **Team API Key** (or User API Key)
- Export it in your shell so Claude Code can pass it to the MCP server:

  ```bash
  export TD_API_KEY="your_api_key_here"
  ```

## 2. Install the plugin in Claude Code

From inside Claude Code, add this repo as a plugin marketplace and install the `testdriver` plugin:

```text
/plugin marketplace add testdriverai/testdriverai
/plugin install testdriver@testdriver
```

That registers three things:

- **`testdriver` MCP server** — spawned via `npx -p testdriverai testdriverai-mcp`, with `TD_API_KEY` forwarded from your environment.
- **`testdriver` sub-agent** — the TestDriver expert agent from `ai/agents/testdriver.md`. Invoke it with `@testdriver ...`.
- **TestDriver skills** — every `ai/skills/testdriver-*` skill, auto-loaded by Claude Code.

## 3. Write tests with the agent

In a Claude Code session, delegate to the agent:

```text
@testdriver Write a test that signs into https://example.com and adds an item to the cart.
```

The agent will use the TestDriver MCP tools (`session_start`, `find`, `click`, `type`, `assert`, …) to interactively build a Vitest test, append generated code to your test file after every action, and run it with `vitest run` until it passes.

For the full agent guide, see the [`testdriver` agent definition](https://github.com/testdriverai/testdriverai/blob/main/ai/agents/testdriver.md) and the [MCP workflow skill](https://github.com/testdriverai/testdriverai/blob/main/ai/skills/testdriver-mcp-workflow/SKILL.md).

## Manual MCP configuration (no plugin)

If you prefer not to use the plugin, you can register the MCP server manually in any MCP-compatible client (Claude Desktop, Cursor, VS Code, …):

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

This is the same config the plugin wires up for you — the plugin just bundles it alongside the agent and skills.

---

## Remote (hosted URL) install — no CLI, browser login

TestDriver also runs a **hosted MCP server** you can connect to with just a URL. There is no `npx` command and no API key to paste: the server speaks OAuth 2.1, so your client opens a browser, you sign in with TestDriver, and the tools appear. It exposes the **full live tool set** (`session_start`, `find`, `click`, `type`, `assert`, …) plus the read-only data tools, all scoped to your team.

Hosted endpoint:

```text
https://mcp.testdriver.ai/mcp
```

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

```text
https://mcp.testdriver.ai/.well-known/oauth-protected-resource
```

Spec-compliant clients discover and complete the OAuth flow automatically:

- **Claude** — add a custom connector pointing at the URL above; Claude runs the browser login for you.
- **VS Code / Copilot** — add a remote MCP server entry with the URL; VS Code handles the OAuth handshake.
- **ChatGPT** — add it as a connector by URL.
- **Any spec-compliant client** — point it at the URL; it will read the metadata, sign you in, and connect.

```json
{
  "mcpServers": {
    "testdriver": {
      "url": "https://mcp.testdriver.ai/mcp"
    }
  }
}
```

Each connection gets its own isolated sandbox, so multiple people (or multiple chats) can run tests at the same time without interfering. The API-key paths above still work for automation and CI.

---

## Observing test runs via HTTP MCP

TestDriver also exposes **test results and analytics** over an HTTP MCP endpoint, so Claude Code (or any MCP-compatible client) can inspect your test runs, failures, and filters without provisioning a sandbox.

### HTTP MCP endpoint contract

The HTTP endpoint lives at:

```text
POST /api/v1/mcp
```

It expects the TestDriver API key in the `X-Api-Key` header (or `Authorization: Bearer <key>`).

Common request shapes:

- **List tools**

```json
{
  "kind": "list_tools"
}
```

- **Call a tool**

```json
{
  "kind": "call_tool",
  "tool": "list_test_runs",
  "arguments": {
    "status": "failed",
    "page": 1,
    "limit": 20
  }
}
```

Responses from tool calls follow the MCP content convention:

```json
{
  "content": [
    {
      "type": "json",
      "json": {
        "testRuns": [],
        "totalCount": 0,
        "hasMore": false
      }
    }
  ]
}
```

### Available tools

The MCP server advertises at least these tools in `list_tools`:

- `list_test_runs`  
  List recent TestDriver test runs for the current team, with filters and pagination.

- `get_test_run_detail`  
  Get a single test run and its test cases (including replay IDs / share keys when available).

- `list_test_cases`  
  List individual test cases for the team with status, duration, error messages, and replay info.

- `get_filter_options`  
  Get branch, suite, repo, filename, commit, status, platform, and test name options for building queries.

### Pointing Claude Code at the HTTP MCP endpoint

You can point Claude Code at the HTTP MCP endpoint using a JSON configuration similar to:

```json
{
  "$schema": "https://schema.anthropic.com/mcp/servers.json",
  "mcpServers": {
    "testdriver-cloud": {
      "type": "sse",
      "url": "https://your-api-host.example.com/api/v1/mcp",
      "requestHeaders": {
        "X-Api-Key": "${TD_API_KEY}"
      },
      "description": "Query TestDriver test runs, test cases, and filters for your team using an API key."
    }
  }
}
```

You can find this exact snippet in the repo at:

- `claude-mcp-config.example.json`

Replace `https://your-api-host.example.com` with your actual API origin (e.g. `https://api.testdriver.ai` or `http://localhost:1337` in development).

### Local development

For local development:

- Run your API server on `http://localhost:1337`
- Point `baseUrl` at `http://localhost:1337/api/v1/mcp`
- Use a local team or user API key in `TD_API_KEY`

```json
{
  "mcpServers": {
    "testdriver-cloud-local": {
      "type": "sse",
      "url": "http://localhost:1337/api/v1/mcp",
      "requestHeaders": {
        "X-Api-Key": "${TD_API_KEY}"
      }
    }
  }
}
```

### Skills documentation for Claude

Claude Code loads the agent and skills automatically when you install the plugin (see step 2). The underlying sources are:

- `ai/agents/testdriver.md` contains the **full TestDriver Agent Guide**
- `ai/skills/testdriver-*/SKILL.md` provide task-specific skills (MCP workflow, assertions, provisioning, etc.)

Use these as the primary reference for:

- How to initialize the `TestDriver` SDK in Vitest
- The MCP workflow for building tests interactively with visual feedback
- How to find elements, click, type, scroll, assert, and capture screenshots

The MCP tools described above are **read-only** helpers for:

- Inspecting recent test runs and failures
- Discovering branches, files, and suites to focus on
- Pulling detailed test case and replay information into Claude for analysis

Use the SDK (`testdriverai`) for **driving tests**, and the HTTP MCP server (`/api/v1/mcp`) for **observing and debugging** them from Claude Code.