Wave Developer Docs

Connect your Wave workspace to any AI assistant supporting the Model Context Protocol (MCP).

Once connected, your AI assistant can inspect outreach campaigns, query connected Instagram sender accounts, analyze lead audience lists, and review live reply performance KPIs directly within your chat or IDE.

MCP Server Endpoint

Parameter	Value
Server URL	`https://api.usewave.co/mcp`
Transport	Streamable HTTP / Server-Sent Events (SSE)
Protocol Version	MCP 2024-11-05+
Supported Clients	Claude Code, Claude Desktop, Claude.ai (Web), Cursor, Windsurf, Zed

Authentication Methods

Wave supports two authentication methods for connecting AI assistants:

Option 1: Direct OAuth 2.1 (Recommended)
Option 2: Developer REST API Key

Native OAuth 2.1 (Zero-Config)

No API keys required! Wave implements RFC 9728 & RFC 8414 OAuth 2.1 with PKCE S256. Your AI assistant will open Wave’s authorization screen in your browser, and tokens are renewed automatically.

Claude Code CLI

Run the following command in your terminal:

claude mcp add --transport sse wave https://api.usewave.co/mcp

Your browser will automatically open Wave’s authorization consent screen.
Sign in with your Wave credentials (or Google OAuth).
Click Authorize Claude — your terminal session will connect immediately.

Claude Desktop & Claude.ai (Web Connectors)

Open Claude and navigate to Settings → Connectors / MCP Servers.
Add a new server named Wave with the URL:
https://api.usewave.co/mcp
Click Connect. When prompted, log in to your Wave account to complete authorization.

Cursor IDE

Open Cursor Settings (Ctrl + Shift + J or Cmd + Shift + J) → Features → MCP.
Click + Add New MCP Server.
Fill in:
- Name: wave
- Type: sse or http
- URL: https://api.usewave.co/mcp
Follow the interactive browser prompt to sign in and authorize.

Windsurf / Codeium

In your ~/.codeium/windsurf/mcp_config.json (or IDE Settings → MCP):

{
  "mcpServers": {
    "wave": {
      "serverUrl": "https://api.usewave.co/mcp"
    }
  }
}

API Key Authentication

If your MCP client or headless server environment does not support interactive browser-based OAuth popups, you can authenticate using a static Wave API key.

1. Generate an API Key

Log in to your Wave Dashboard.
Go to Settings → Developer REST API Keys (/settings).
Click Create New Key, give it a name, and copy the secret token (wave_...).

Workspaces can have up to 2 active API keys at any time. Keep your secret key secure; it will not be shown again.

2. Include in Authorization Header

Pass your key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_WAVE_API_KEY

Claude Desktop Configuration

Add Wave to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wave": {
      "url": "https://api.usewave.co/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_WAVE_API_KEY"
      }
    }
  }
}

Claude Code CLI with API Key

claude mcp add wave --transport http https://api.usewave.co/mcp \
  --header "Authorization: Bearer YOUR_WAVE_API_KEY"

Cursor IDE (`settings.json`)

{
  "mcpServers": {
    "wave": {
      "url": "https://api.usewave.co/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_WAVE_API_KEY"
      }
    }
  }
}

Available Tools Reference

Wave MCP exposes 14 production tools across 5 distinct outreach domains:

1. Outreach Campaigns

list_campaigns — List all outreach campaigns

Returns all outreach campaigns in your workspace with execution state, daily dispatch quotas, and progress stats.

Input Parameters:
- status (string, optional) — Filter by status: PENDING, IN_PROGRESS, PAUSED, or COMPLETED.
- active (boolean, optional) — Filter by active toggle (true / false).
Returns: Campaign ID, title, status, daily limit, connected sender accounts count, total leads, DMs sent, and reply counts.

get_campaign — Get campaign details & live metrics

Retrieves deep configuration and execution details for a specific campaign.

Input Parameters:
- campaign_id (string, required) — The unique identifier of the campaign.
Returns: Attached sender Instagram accounts, linked audience lead lists, assigned message sequences, dispatch schedule (working hours, active days), and granular reply conversion rates.

create_campaign — Create and initialize a new campaign

Creates a new Instagram DM campaign with built-in safety limits and schedule parameters.

Input Parameters:
- title (string, required) — Descriptive title of the campaign.
- account_ids (array of strings, required) — List of connected sender account IDs.
- audience_id (string, required) — ID of the target audience list.
- sequence_id (string, required) — ID of the message sequence to dispatch.
- daily_limit (integer, optional, default: 20) — Maximum outreach DMs per account per day.
- dry_run (boolean, optional, default: false) — When true, validates configuration and sender health without creating the campaign.
Returns: Created campaign summary or validation confirmation.

control_campaign — Pause, resume, or adjust campaign settings

Dynamically adjusts execution parameters or pauses outreach without entering the web UI.

Input Parameters:
- campaign_id (string, required) — Target campaign ID.
- action (string, required) — One of: pause, resume, or update_settings.
- daily_limit (integer, optional) — Updated daily sending quota.
- active_days (array of strings, optional) — Days of week to run outreach.

2. Target Audiences & Lead Lists

list_audiences — List all audience lead lists

Lists all target lead lists with source types, scraping statuses, and AI filtration progress.

Input Parameters:
- type (string, optional) — Filter by list type: FOLLOWERS or POSTS.
Returns: List ID, name, list type, total leads scraped, leads passed AI filtration, and status (READY, PROCESSING, FAILED).

create_audience — Create new audience & trigger AI filtration

Creates a new lead audience list and initiates automated background scraping and bio/activity filtration.

Input Parameters:
- name (string, required) — Name for the audience list.
- type (string, required) — FOLLOWERS (scrapes followers of target accounts) or POSTS (scrapes commenters/likers of target posts).
- targets (array of strings, required) — Target Instagram usernames or post URLs.
- filter_criteria (object, optional) — AI filtering rules (e.g. min/max followers, required keywords, language, verified accounts only).

3. Message Sequences & Templates

list_sequences — List outreach sequences

Lists all outreach message sequences with step counts, follow-up stages, and pre-DM warming actions.

Returns: Sequence ID, name, initial message count (spintax variants), follow-up step count, and actions (FOLLOW_FIRST, LIKE_LAST_POSTS).

get_sequence — Get sequence details and message variants

Fetches the full sequence configuration including spintax variations, follow-up delay days, and warm-up actions.

Input Parameters:
- sequence_id (string, required) — Sequence ID.

create_sequence — Create a new multi-step sequence

Creates a message sequence with initial spintax copy, smart delays, and follow-up templates.

Input Parameters:
- name (string, required) — Descriptive name.
- messages (array of strings, required) — Initial message templates (supports spintax: {Hi|Hey|Hello}).
- follow_ups (array of objects, optional) — Follow-up steps with delay days and conditions.
- follow_first (boolean, optional) — Follow the lead before sending DM.
- like_posts (integer, optional) — Number of recent posts to like before DMing.

update_sequence — Update sequence copy and actions

Edits existing message copy, adjusts delays between follow-ups, or toggles warming actions.

Input Parameters:
- sequence_id (string, required) — Sequence ID to update.
- messages (array of strings, optional) — Updated message variations.
- follow_ups (array of objects, optional) — Updated follow-up schedules.

4. Instagram Sender Accounts

list_accounts — List connected Instagram senders

Lists all connected sender Instagram accounts in the workspace with current session statuses and daily sending quotas.

Input Parameters:
- status (string, optional) — Filter by connection status: READY, WARMING_UP, CHALLENGE, or SUSPENDED.
Returns: Account ID, username, status, warm-up day count, and daily dispatched count.

get_account_health — Deep health check on sender account

Conducts a real-time health diagnostic on a sender account to evaluate checkpoint risks, login validity, and outreach safety.

Input Parameters:
- account_id (string, required) — Account ID.
Returns: Session status, challenge flag details, warmup health score, and recommended daily sending limit.

5. Analytics & Workspace KPIs

get_workspace_overview — Lifetime performance KPIs

Returns aggregate performance metrics across all campaigns and sender accounts.

Returns: Total campaigns, total initial DMs sent, follow-ups sent, total replies received, aggregate reply rate percentage, and active accounts.

get_daily_analytics — Daily outreach timeline breakdown

Returns a day-by-day time-series breakdown of DMs dispatched and replies received.

Input Parameters:
- start_date (string, optional) — Start date (YYYY-MM-DD). Defaults to 30 days ago.
- end_date (string, optional) — End date (YYYY-MM-DD). Defaults to today.
- campaign_id (string, optional) — Filter metrics by specific campaign.
Returns: Array of daily timeline data points with date, dms_sent, follow_ups_sent, replies, and reply_rate.

Security, Rate Limits & Tokens

OAuth Token Lifetime: Access tokens issued via OAuth 2.1 are valid for 30 days and include an automatic refresh token valid for 90 days.
Rate Limits: MCP endpoints are protected with per-account rate limiters. Standard accounts receive up to 60 requests/minute.
Subscription Requirement: Access to Wave MCP tools requires an active Wave Pro subscription or valid trial.
Granular Scope Control: All actions respect workspace permissions and sender safety limits to prevent Instagram action blocks.

Troubleshooting

Error: 401 Unauthorized

OAuth Users: Your session may have expired. Disconnect and re-run claude mcp add --transport sse wave https://api.usewave.co/mcp to re-authorize.
API Key Users: Ensure your Authorization: Bearer <key> header includes the full key string without extra spaces, and verify in Wave Settings that the key has not been revoked.

Error: 403 Subscription Required

Wave MCP requires an active subscription or free trial. Visit the Wave Billing Page to renew your workspace subscription.

Browser authorization window does not open

If running Claude Code or Cursor inside a remote SSH session or headless container, copy the authorization URL displayed in the terminal output and paste it into your local browser.

​Connect your Wave workspace to any AI assistant supporting the Model Context Protocol (MCP).

​MCP Server Endpoint

​Authentication Methods

​Native OAuth 2.1 (Zero-Config)

​Claude Code CLI

​Claude Desktop & Claude.ai (Web Connectors)

​Cursor IDE

​Windsurf / Codeium

​API Key Authentication

​1. Generate an API Key

​2. Include in Authorization Header

​Claude Desktop Configuration

​Claude Code CLI with API Key

​Cursor IDE (settings.json)

​Available Tools Reference

​1. Outreach Campaigns

​2. Target Audiences & Lead Lists

​3. Message Sequences & Templates

​4. Instagram Sender Accounts

​5. Analytics & Workspace KPIs

​Security, Rate Limits & Tokens

​Troubleshooting

Connect your Wave workspace to any AI assistant supporting the Model Context Protocol (MCP).

MCP Server Endpoint

Authentication Methods

Native OAuth 2.1 (Zero-Config)

Claude Code CLI

Claude Desktop & Claude.ai (Web Connectors)

Cursor IDE

Windsurf / Codeium

API Key Authentication

1. Generate an API Key

2. Include in Authorization Header

Claude Desktop Configuration

Claude Code CLI with API Key

Cursor IDE (`settings.json`)

Available Tools Reference

1. Outreach Campaigns

2. Target Audiences & Lead Lists

3. Message Sequences & Templates

4. Instagram Sender Accounts

5. Analytics & Workspace KPIs

Security, Rate Limits & Tokens

Troubleshooting