# Connect AI to Your A/B Tests

Use the Model Context Protocol (MCP) to manage experiments, analyze results, and automate your testing workflow from Claude Code, Claude Desktop, Cursor, VS Code, and more.

Get your API key from your Otter dashboard under **Settings → API & MCP**, or see the [REST API Reference](https://www.otterab.com/api-docs).

## What is MCP?

The **Model Context Protocol (MCP)** is an open standard that lets AI assistants connect to external tools and data sources. Instead of copy-pasting API responses, your AI assistant can directly manage your Otter experiments.

- **Conversational** — Ask in plain English: "Create a redirect test on the pricing page" and the AI handles the API calls.
- **Same API Key** — Use the same account-scoped API key you already created for the REST API. No additional auth needed.
- **Scoped & Safe** — API key scopes and project restrictions apply to MCP too. Read-only keys stay read-only.

## Prerequisites

Before connecting MCP, you need an Otter API key.

1. **Create an API key** — Go to **Settings → API & MCP** in your Otter dashboard and create a new API key. Select the scopes you want the AI assistant to have access to.
2. **Copy the token** — The full token (e.g. `oab_live_abc123_9f8e7d...`) is only shown once. Store it in a safe place.
3. **Choose recommended scopes** — For full MCP functionality, we recommend these scopes: `projects:read`, `projects:write`, `experiments:read`, `experiments:write`, `results:read`, `account:read`.

> **Note:** For read-only access (results inspection only), use: `projects:read`, `experiments:read`, `results:read`

## Remote Hosted URL

The simplest way to connect. Use our hosted MCP endpoint directly — no local installation required. Your API key is embedded in the URL.

```bash
https://www.otterab.com/mcp/YOUR_API_KEY/v2/mcp
```

Replace `YOUR_API_KEY` with your full API key (e.g. `oab_live_abc123_9f8e7d...`). This URL works with MCP clients that support remote HTTP MCP servers.

## Claude Code

Add Otter to Claude Code with a single command.

```bash
# Remote hosted URL (recommended)
claude mcp add --transport http otterab https://www.otterab.com/mcp/YOUR_API_KEY/v2/mcp

# Or run locally via npx
claude mcp add --transport stdio --env OTTERAB_API_KEY=oab_live_... otterab -- npx -y @otterab/mcp
```

Then start using it:

```text
> claude

You: List my running experiments on the Marketing Site project
Claude: I found 3 running experiments on "Marketing Site":
  1. Pricing Hero Test - running since March 15
  2. Homepage CTA Color - running since March 20
  3. Nav Redesign v2 - running since March 25

You: How is the Pricing Hero Test performing?
Claude: The "Pricing Hero Test" is performing well:
  - Control: 8.36% conversion rate (1,412 visitors)
  - Clearer Headline: 10.72% conversion rate (1,408 visitors)
  - Decision score: 96.1% with +28.2% improvement
  The "Clearer Headline" variant has crossed the decision threshold and is the current winner.
```

## Claude Desktop

Add to your `claude_desktop_config.json` file via **Settings → Developer → Edit Config**.

```json
{
  "mcpServers": {
    "otterab": {
      "url": "https://www.otterab.com/mcp/YOUR_API_KEY/v2/mcp"
    }
  }
}
```

If your Claude Desktop version doesn't support remote HTTP MCP servers, use the local npx approach instead (requires [Node.js](https://nodejs.org)):

```json
{
  "mcpServers": {
    "otterab": {
      "command": "npx",
      "args": ["-y", "@otterab/mcp"],
      "env": {
        "OTTERAB_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

Restart Claude Desktop after editing the config. You should see Otter tools in the tools menu.

## Cursor

Go to **Settings → Features → MCP Servers** and click "+ Add new global MCP server".

```json
{
  "mcpServers": {
    "otterab": {
      "command": "npx",
      "args": ["-y", "@otterab/mcp"],
      "env": {
        "OTTERAB_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

## VS Code

Open your MCP configuration via **Ctrl+Shift+P → MCP: Open User Configuration**, or create `.vscode/mcp.json` in your workspace.

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Otter API Key",
      "password": true
    }
  ],
  "servers": {
    "otterab": {
      "command": "npx",
      "args": ["-y", "@otterab/mcp"],
      "env": {
        "OTTERAB_API_KEY": "${input:apiKey}"
      }
    }
  }
}
```

You can also add this to `.vscode/mcp.json` in your workspace to share with your team.

## Windsurf

Add to your `~/.codeium/windsurf/mcp_config.json`.

```json
{
  "mcpServers": {
    "otterab": {
      "command": "npx",
      "args": ["-y", "@otterab/mcp"],
      "env": {
        "OTTERAB_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

## Running with npx

Run the MCP server locally using npx. Requires [Node.js 18+](https://nodejs.org).

```bash
# Run with npx (auto-installs)
env OTTERAB_API_KEY=oab_live_... npx -y @otterab/mcp

# Or install globally
npm install -g @otterab/mcp
OTTERAB_API_KEY=oab_live_... otterab-mcp
```

### Streamable HTTP mode

To run the server as an HTTP endpoint (for n8n, custom integrations, etc.):

```bash
env HTTP_STREAMABLE_SERVER=true OTTERAB_API_KEY=oab_live_... npx -y @otterab/mcp
# Server starts at http://localhost:3000/v2/mcp
```

### Environment variables

| Variable | Required | Description |
| --- | --- | --- |
| `OTTERAB_API_KEY` | Yes | Your Otter API key |
| `OTTERAB_API_URL` | No | Custom API base URL (for self-hosted) |
| `HTTP_STREAMABLE_SERVER` | No | Set to "true" for HTTP transport |
| `PORT` | No | HTTP server port (default: 3000) |
| `HOST` | No | HTTP server host (default: 127.0.0.1) |

## Available Tools

The MCP server exposes 30 tools organized by category. Each tool maps to a customer job, not a raw CRUD operation.

### Projects

| Tool | Description |
| --- | --- |
| `list_projects` | List all projects accessible to this API key. |
| `get_project` | Get details for a specific project by ID. |
| `create_project` | Create a new project with a name, URL, and platform. |
| `update_project` | Update a project. Only provided fields are changed. |
| `delete_project` | Permanently delete a project and all its experiments. |
| `get_project_stats` | Get aggregate statistics for a project, including lifetime totals and last-30-day metrics. |
| `get_project_installation` | Get installation metadata, SDK snippets, and verification status. |

### Experiments

| Tool | Description |
| --- | --- |
| `list_experiments` | List experiments for a project, optionally filtered by status. |
| `get_experiment` | Get full experiment details including variants, goals, and targeting. |
| `create_experiment_draft` | Create a new experiment with variants, goals, and targeting in one call. |
| `update_experiment_draft` | Update a draft or safely edit a paused experiment with stable IDs. |
| `delete_experiment` | Delete a draft experiment. |
| `start_experiment` | Start a draft experiment. Requires 2+ variants and 1+ goals. |
| `pause_experiment` | Pause a running experiment. |
| `resume_experiment` | Resume a paused experiment. |
| `complete_experiment` | Complete a running or paused experiment. |
| `archive_experiment` | Archive a completed experiment. |
| `inspect_page` | Load one of your pages in a real browser and return its elements with working CSS selectors. Call this before authoring visual changes so selectors match real elements. |
| `quick_create_redirect_experiment` | One-step creation of a redirect experiment with source URL, redirect URL, and goal. |
| `quick_create_visual_experiment` | One-step creation of a visual experiment with element changes and goal. |

### Results

| Tool | Description |
| --- | --- |
| `get_experiment_results` | Get results for an experiment across all goals with optional segment filters. |
| `get_experiment_results_summary` | Get a simplified summary for the primary goal with optional segment filters. |
| `get_experiment_timeseries` | Get daily time series data for charting with optional segment filters. |

### Account & Capabilities

| Tool | Description |
| --- | --- |
| `list_targeting_fields` | List available targeting fields and operators for building rules. |
| `list_goal_types` | List supported goal types. |
| `list_experiment_types` | List supported experiment types. |
| `list_visual_change_actions` | List supported visual change actions. |
| `get_account` | Get account details and plan information. |
| `get_account_members` | List all team members on the account. |
| `get_account_usage` | Get plan limits and current usage. |

## Usage Examples

Here are common workflows you can accomplish with the MCP integration.

### Create a redirect experiment

Ask your AI assistant in natural language:

> "Create a redirect experiment on the pricing page that sends half of traffic to /pricing-v2 and measures signup completion."

The AI calls:

```json
{
  "tool": "quick_create_redirect_experiment",
  "input": {
    "project_id": "42",
    "name": "Pricing V2 Redirect Test",
    "source_url": "https://example.com/pricing",
    "redirect_url": "https://example.com/pricing-v2",
    "goal_name": "Signup Complete",
    "goal_type": "pageview",
    "goal_config": { "url": "https://example.com/signup/success" }
  }
}
```

### Analyze experiment results

Ask for a results breakdown:

> "How is the Homepage CTA experiment performing? Show me the results by country."

The AI calls:

```json
{
  "tool": "get_experiment_results",
  "input": {
    "project_id": "42",
    "experiment_id": "92",
    "country": "US"
  }
}
```

### Manage experiment lifecycle

Control experiments with simple commands:

> "Pause the pricing test"
>
> "Resume the nav redesign experiment"
>
> "Complete the homepage CTA test and show me the final results"

The AI calls the appropriate lifecycle tool:

```json
{
  "tool": "complete_experiment",
  "input": {
    "project_id": "42",
    "experiment_id": "92"
  }
}
```

## Troubleshooting

Common issues and how to resolve them.

### "Couldn't reach the MCP server"

Your MCP client may not support remote HTTP MCP servers yet. Try the npx approach instead: `claude mcp add --transport stdio --env OTTERAB_API_KEY=your-key otterab -- npx -y @otterab/mcp`

### "Tools not showing up in Claude Desktop"

Make sure you fully quit and reopened Claude Desktop after editing the config. Check that the config file is valid JSON.

### "Authentication failed" or "invalid_api_key"

Double-check that the API key is correct and not revoked. Make sure the OTTERAB_API_KEY environment variable is set in your client. The Live and Test environment options on a key are organizational labels — both work against your real account data — so the prefix (oab_live_ vs oab_test_) does not affect what the key can access, only how you choose to label it.

### "Missing required scope"

Your API key doesn't have the required scopes for that action. Create a new key with the needed scopes in Settings > API & MCP.

### "Rate limit exceeded"

You've hit your plan's API rate limit. Wait a minute and try again, or upgrade your plan for higher limits. Starter: 100/min, Growth: 500/min, Scale: 2,000/min.

### "npx command not found"

Make sure Node.js (v18+) is installed. You can download it from nodejs.org.

### Still stuck?

Contact us at [support@otterab.com](mailto:support@otterab.com) with your error message and we'll help you get connected.