/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:

  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:

/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:

@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, …):

{
  "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:

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:

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.

{
  "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:

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**

{
  "kind": "list_tools"
}

• **Call a tool**

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

Responses from tool calls follow the MCP content convention:

{
  "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:

{
  "$schema": "https://schema.anthropic.com/mcp/servers.json",
  "mcpServers": {
    "testdriver-cloud": {
      "type": "sse",