MCP Setup

TestDriver runs a hosted Model Context Protocol server. There is nothing to install and no API key to paste. Add one URL to your AI client, sign in through the browser, and the computer-use tools appear in chat.

https://mcp.testdriver.ai/mcp

Prerequisites

An MCP-compatible AI client (Claude, Claude Code, VS Code, Cursor, ChatGPT, and others)
A TestDriver account. Create one for free. You get 60 device minutes, no credit card required.

Add the server

Most clients accept the URL directly. Pick yours below.

Open Settings → Connectors → Add custom connector.
Paste https://mcp.testdriver.ai/mcp.
Click Connect and sign in with TestDriver when the browser opens.

claude mcp add --transport http testdriver https://mcp.testdriver.ai/mcp

Run /mcp in a session to start the browser login and confirm the tools are connected.

Add this to .vscode/mcp.json in your project. VS Code uses the servers key:

.vscode/mcp.json

{
  "servers": {
    "testdriver": {
      "type": "http",
      "url": "https://mcp.testdriver.ai/mcp"
    }
  }
}

VS Code prompts you to authorize the server the first time you use it.

Add this to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

.cursor/mcp.json

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

Open Settings → Connectors → Create.
Paste https://mcp.testdriver.ai/mcp as the MCP server URL.
Choose OAuth for authentication and sign in with TestDriver.

Any spec-compliant client works. Point it at the URL using the streamable HTTP transport:

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

Clients disagree on the top-level key. VS Code uses servers, most others use mcpServers, Zed uses context_servers, and Codex uses TOML [mcp_servers]. If the tools do not show up, check the key before anything else.

The server speaks OAuth 2.1 and advertises its authorization server via RFC 9728 protected-resource metadata:

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

Spec-compliant clients read that metadata, open a browser, and complete the handshake for you. Every tool is scoped to the team you sign in with.

Verify it works

Ask your client to drive a browser:

Use TestDriver to open example.com and assert the page title is visible.

The agent starts a sandbox and returns a screenshot with every action. Each connection gets its own isolated sandbox, so multiple people and multiple chats can run tests at the same time without interfering.

What you get

The hosted server exposes the full live tool set:

Tool	Purpose
`session_start`, `session_status`, `session_extend`	Start a sandbox, check its health, add more time
`find`, `findall`, `find_and_click`	Locate elements by plain-English description
`click`, `hover`, `type`, `press_keys`, `scroll`	Perform actions
`assert`, `check`	Ask yes/no questions about the screen
`screenshot`, `exec`, `wait`, `focus_application`	Capture state, run commands, pause

Every action also returns the SDK code for that step, so the agent can write a runnable Vitest test as it goes.

Local server for CI and automation

For headless automation, or when you would rather use an API key than a browser login, run the server as a local stdio process:

npx -p testdriverai testdriverai-mcp

It reads TD_API_KEY from the environment. Generate a key at console.testdriver.ai/settings.

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

npx testdriverai init writes this config for you, plus the TestDriver agent, skills, an example test, and a GitHub Actions workflow. See Setting up your workspace.

Troubleshooting

The tools do not appear in my client

Confirm the URL is exactly https://mcp.testdriver.ai/mcp, check that you used the correct top-level config key for your client, and restart the client. Most clients read their MCP config only at startup.

I ran out of device minutes

Sandbox time is billed per minute. Check your usage and plan at console.testdriver.ai.

The sandbox expired mid-session

Sessions time out after a period of inactivity. Ask the agent to call session_extend before it expires, or session_start to get a fresh sandbox.

Next steps

Generating tests

Prompting patterns that get the best tests out of the agent.

Setting up your workspace

Add the SDK to a project so generated tests run locally and in CI.

Walkthrough

Provision apps, locate elements, perform actions, and make assertions.

CI/CD

Run your tests on every pull request.

Overview

Using TestDriver

Building & Maintaining Tests

Advanced Topics

Add the server

Verify it works

What you get

Local server for CI and automation

Troubleshooting

Next steps

Generating tests

Setting up your workspace

Walkthrough

CI/CD

​Add the server

​Sign in

​Verify it works

​What you get

​Local server for CI and automation

​Troubleshooting

​Next steps

Generating tests

Setting up your workspace

Walkthrough

CI/CD

Add the server

Sign in

Verify it works

What you get

Local server for CI and automation

Troubleshooting

Next steps