# Connect Claude (Desktop & CLI)

:::lead
Connect Claude Desktop and the Claude Code CLI to TestOwl through the Model Context Protocol (MCP) to record, describe, and generate tests with your own Anthropic account without consuming TestOwl AI credits.
:::

TestOwl Desktop includes a built-in Model Context Protocol (MCP) server bridge. When connected, your local Claude AI tools can communicate directly with TestOwl to author tests, analyze DOM snapshots, and execute user journeys.

## Key Capabilities

- **Zero TestOwl AI Credit Consumption:** Test generation and AI Describe queries run directly through your local Claude account, preserving your TestOwl platform credit quota.
- **Bi-Directional Tooling:** Claude Desktop can generate and author tests inside your TestOwl workspace, while TestOwl can invoke Claude Code for local test analysis.
- **Private & Local:** All communication between Claude and TestOwl occurs over a secure, owner-only local inter-process channel on your machine.

## Prerequisites

1. **TestOwl Desktop App:** Installed and running on Windows or macOS.
2. **Eligible Plan:** Claude Connect is available on plans with Desktop and AI capabilities.
3. **Claude Installation:**
   - **Claude Code CLI:** Installed (`claude` in your terminal) and signed in.
   - **Claude Desktop:** Installed on your computer.

## Configuring Claude Connect in TestOwl

Open the TestOwl Desktop App and navigate to **Settings → Connect Claude** (or open **Project Settings → Manage Claude**).

### 1. Connecting Claude Code CLI

The **Claude Code CLI** card automatically assesses your environment:
- **Ready (Green):** Claude Code is installed and authenticated.
- **Login Required (Yellow):** Claude Code is installed but not authenticated. Run `claude` in your terminal to sign in, then click **Check again**.
- **Not Found:** If Claude Code is installed in a non-standard directory, click **Change location** and enter the path to the executable.
- **Connect MCP:** Click **Connect Claude CLI (MCP)**. TestOwl automatically registers its local MCP server bridge in `~/.claude.json` while safely preserving a `.testowl-backup` file.

### 2. Connecting Claude Desktop

1. In the **Claude Desktop** card, click **Connect Claude Desktop** (or **Reconnect Claude Desktop** if updating).
2. TestOwl automatically updates your Claude Desktop configuration file:
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
3. Existing custom MCP servers in your configuration are preserved, and an automatic backup (`claude_desktop_config.json.testowl-backup`) is created.
4. Restart Claude Desktop to activate the new TestOwl tools.

## Using Claude in TestOwl

### The "Run with" AI Provider Switch

When authoring tests in the TestOwl dashboard or recorder, look for the **Run with** switch in the AI panel footer:
- **TestOwl AI:** Uses TestOwl's managed cloud AI engine and consumes workspace AI credits.
- **Claude:** Uses your connected local Claude Code / Claude account with zero credit consumption.

*Note:* If Claude is selected but Claude Code is not running or logged in, TestOwl displays an alert banner with a direct link to *Settings → Connect Claude*.

### Headless and Headful Test Generation

When generating tests with Claude:
- **Headless Mode:** Claude plans and executes the test in a background browser. It validates each step, performing up to three check runs and two self-healing repairs. Once all steps pass, it hands back an unsaved test case for your review and confirmation.
- **Headful Mode:** Claude executes inside an active recorder session. You can watch Claude navigate, interact with elements, inspect DOM mutations live, and step in at any point.

## Disconnecting Claude

To disconnect Claude at any time:
1. Go to **Settings → Connect Claude** in the Desktop App.
2. Click **Disconnect Claude**.
3. TestOwl cleanly removes its server entries from `claude_desktop_config.json` and `~/.claude.json` and closes the local MCP channel.

## Next steps

::::cardgrid
:::card{title="Creating Tests with AI" href="/docs/building-tests/creating-tests-with-ai"}
See how the "Run with" switch works in practice when building a test.
:::

:::card{title="AI Credits and Usage Limits" href="/docs/team-and-account/ai-credits"}
Compare TestOwl AI's credit allowance with Claude's zero-credit path.
:::
::::