> ## Documentation Index
> Fetch the complete documentation index at: https://developers.usewave.co/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Setup

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

<Tabs>
  <Tab title="Option 1: Direct OAuth 2.1 (Recommended)">
    ### Native OAuth 2.1 (Zero-Config)

    <Tip>
      **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.
    </Tip>

    #### Claude Code CLI

    Run the following command in your terminal:

    ```bash theme={null}
    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)

    1. Open **Claude** and navigate to **Settings → Connectors / MCP Servers**.
    2. Add a new server named `Wave` with the URL:
       ```text theme={null}
       https://api.usewave.co/mcp
       ```
    3. Click **Connect**. When prompted, log in to your Wave account to complete authorization.

    #### Cursor IDE

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

    #### Windsurf / Codeium

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

    ```json theme={null}
    {
      "mcpServers": {
        "wave": {
          "serverUrl": "https://api.usewave.co/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Option 2: Developer REST API Key">
    ### 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

    1. Log in to your [Wave Dashboard](https://app.usewave.co/).
    2. Go to **Settings → Developer REST API Keys** (`/settings`).
    3. Click **Create New Key**, give it a name, and copy the secret token (`wave_...`).

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

    #### 2. Include in Authorization Header

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

    ```http theme={null}
    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`

    ```json theme={null}
    {
      "mcpServers": {
        "wave": {
          "url": "https://api.usewave.co/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_WAVE_API_KEY"
          }
        }
      }
    }
    ```

    #### Claude Code CLI with API Key

    ```bash theme={null}
    claude mcp add wave --transport http https://api.usewave.co/mcp \
      --header "Authorization: Bearer YOUR_WAVE_API_KEY"
    ```

    #### Cursor IDE (`settings.json`)

    ```json theme={null}
    {
      "mcpServers": {
        "wave": {
          "url": "https://api.usewave.co/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_WAVE_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

***

## Available Tools Reference

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

### 1. Outreach Campaigns

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

### 2. Target Audiences & Lead Lists

<AccordionGroup>
  <Accordion title="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`).
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

***

### 3. Message Sequences & Templates

<AccordionGroup>
  <Accordion title="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`).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

### 4. Instagram Sender Accounts

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

### 5. Analytics & Workspace KPIs

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>

***

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Error: 403 Subscription Required">
    Wave MCP requires an active subscription or free trial. Visit the [Wave Billing Page](https://app.usewave.co/settings/billing) to renew your workspace subscription.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.