testdriver:claude-mcp-plugin

<!-- Generated from claude-mcp-plugin.mdx. DO NOT EDIT. -->

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.

---

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