MCP Setup

Connect any AI client to TestDriver by adding one URL.

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.

Claude

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

Claude Code

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.

VS Code

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.

Cursor

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

.cursor/mcp.json

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

ChatGPT

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

Other clients

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.

Sign in

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.

The browser login never completes

Your client must support OAuth 2.1 with Dynamic Client Registration. Older clients, and clients that only support stdio servers, cannot connect to the hosted URL. Use the local server with TD_API_KEY instead.

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.