MCP Integration

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 KeyREST API Reference

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 A/B 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 A/B API key.

1

Create an API key

Go to Settings → API & MCP in your Otter A/B dashboard and create a new API key. Select the scopes you want the AI assistant to have access to.

Open Settings
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:readprojects:writeexperiments:readexperiments:writeresults:readaccount:read

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.

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 A/B to Claude Code with a single command.

# 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:

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

{
  "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):

{
  "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 A/B tools in the tools menu.

Cursor

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

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

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Otter A/B 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.

{
  "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+.

# 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.):

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

Environment variables

VariableRequiredDescription
OTTERAB_API_KEYYesYour Otter A/B API key
OTTERAB_API_URLNoCustom API base URL (for self-hosted)
HTTP_STREAMABLE_SERVERNoSet to "true" for HTTP transport
PORTNoHTTP server port (default: 3000)
HOSTNoHTTP server host (default: 127.0.0.1)

Available Tools

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

Projects

list_projectsprojects

List all projects accessible to this API key.

get_projectprojects

Get details for a specific project by ID.

create_projectprojects

Create a new project with a name, URL, and platform.

update_projectprojects

Update a project. Only provided fields are changed.

delete_projectprojects

Permanently delete a project and all its experiments.

get_project_statsprojects

Get aggregate statistics for a project, including lifetime totals and last-30-day metrics.

get_project_installationprojects

Get installation metadata, SDK snippets, and verification status.

Experiments

list_experimentsexperiments

List experiments for a project, optionally filtered by status.

get_experimentexperiments

Get full experiment details including variants, goals, and targeting.

create_experiment_draftexperiments

Create a new experiment with variants, goals, and targeting in one call.

update_experiment_draftexperiments

Update a draft experiment. Replaces variants and goals.

delete_experimentexperiments

Delete a draft experiment.

start_experimentexperiments

Start a draft experiment. Requires 2+ variants and 1+ goals.

pause_experimentexperiments

Pause a running experiment.

resume_experimentexperiments

Resume a paused experiment.

complete_experimentexperiments

Complete a running or paused experiment.

archive_experimentexperiments

Archive a completed experiment.

quick_create_redirect_experimentexperiments

One-step creation of a redirect experiment with source URL, redirect URL, and goal.

quick_create_visual_experimentexperiments

One-step creation of a visual experiment with element changes and goal.

Results

get_experiment_resultsresults

Get results for an experiment across all goals with optional segment filters.

get_experiment_results_summaryresults

Get a simplified summary for the primary goal with optional segment filters.

get_experiment_timeseriesresults

Get daily time series data for charting with optional segment filters.

Account & Capabilities

list_targeting_fieldsaccount

List available targeting fields and operators for building rules.

list_goal_typesaccount

List supported goal types.

list_experiment_typesaccount

List supported experiment types.

list_visual_change_actionsaccount

List supported visual change actions.

get_accountaccount

Get account details and plan information.

get_account_membersaccount

List all team members on the account.

get_account_usageaccount

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:

{
  "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:

{
  "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:

{
  "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 your API key is correct and not revoked. Make sure the OTTERAB_API_KEY environment variable is set. Keys starting with oab_test_ only work with test data.

"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 with your error message and we'll help you get connected.