testdriver:claude-mcp-plugin

TestDriver ships as a native Claude Code plugin 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 and the MCP workflow skill.

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.

---

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",
      "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

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