# MCP server for AI assistants

> Connect Claude, Cursor, VS Code, ChatGPT, Gemini CLI or Codex CLI to your WhatSetter workspace with 66 MCP tools, one API key and no code.

Source: https://docs.whatsetter.com/developers/mcp/

**MCP** (Model Context Protocol) is the open standard that lets an AI assistant use a piece of software through tools. The WhatSetter MCP server exposes **66 tools**, one per API endpoint, so your assistant can read your leads and your Instagram and Messenger conversations, import contacts, block a dial prefix, or explain why an agent said something and correct its prompt, all from a chat.

## The server

| Item | Value |
|---|---|
| URL | `https://mcp.whatsetter.com/mcp` |
| Transport | Streamable HTTP. `https://mcp.whatsetter.com/sse` still works for older clients. |
| Authentication | OAuth (recommended) or a direct `Authorization: Bearer ws_live_…` header |
| What it needs | An API key created in **Settings**, then **API & MCP** |

The server is a thin translator: every tool call is a call to the REST API with your key. Scopes, rate limits and the [anti-ban rules](/dashboard/anti-ban/) apply exactly as they do for the API.

## Two ways to authenticate

**OAuth.** You add the server URL in your client. The client opens a WhatSetter consent page in your browser; you paste your `ws_live_…` key once and click **Authorize**. The client then holds a revocable token and never sees the key again. Use this for Claude, ChatGPT, Cursor, VS Code and any client that supports OAuth.

**Direct bearer.** You pass the key yourself, in an `Authorization: Bearer ws_live_…` header. Use this for scripts, servers and clients where you prefer to manage the secret in an environment variable.

```
POST https://mcp.whatsetter.com/mcp
Authorization: Bearer ws_live_…
```

Either way, revoking the key in the dashboard cuts the connection within a minute.

## Claude Code

Add the server, then run `/mcp` inside Claude Code to open the consent page:

```bash
claude mcp add --transport http whatsetter https://mcp.whatsetter.com/mcp
```

To use the key directly instead of OAuth:

```bash
claude mcp add --transport http whatsetter https://mcp.whatsetter.com/mcp \
  --header "Authorization: Bearer ws_live_…"
```

Add `--scope user` to make the server available in every project instead of the current one.

## Claude (web and desktop app)

Custom connectors are configured in your Claude account and then available in the web app and in the Claude desktop app.

1. Open **Customize**, then **Connectors**.
2. Click **+**, then **Add custom connector**.
3. Paste `https://mcp.whatsetter.com/mcp` as the remote MCP server URL, then click **Add**.
4. A WhatSetter page opens: paste your API key and click **Authorize**.

## Cursor

Click the install link, or add the server to `~/.cursor/mcp.json` by hand. Cursor opens the consent page on first use.

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=whatsetter&config=eyJ1cmwiOiJodHRwczovL21jcC53aGF0c2V0dGVyLmNvbS9tY3AifQ==">Add WhatSetter to Cursor</a>

```json
{
  "mcpServers": {
    "whatsetter": {
      "url": "https://mcp.whatsetter.com/mcp"
    }
  }
}
```

To use the key directly, add a `headers` object with `"Authorization": "Bearer ws_live_…"` to the same entry.

## VS Code

From the command line, or in `.vscode/mcp.json` (or your user profile via **MCP: Open User Configuration**). VS Code runs the OAuth flow in your browser on first connection.

```bash
code --add-mcp '{"name":"whatsetter","type":"http","url":"https://mcp.whatsetter.com/mcp"}'
```

```json
{
  "servers": {
    "whatsetter": {
      "type": "http",
      "url": "https://mcp.whatsetter.com/mcp"
    }
  }
}
```

## ChatGPT

Remote MCP servers are available to Pro, Plus, Business, Enterprise and Education accounts on the web, after enabling developer mode.

1. Open **Settings**, then **Security and login**, and turn on **Developer mode**.
2. Go to `chatgpt.com/plugins` and select the plus button to create an app for your MCP server.
3. Give it a name, and under **Connection** enter `https://mcp.whatsetter.com/mcp` as the MCP server URL.
4. Choose OAuth as the authentication and complete the WhatSetter consent page.

In a conversation, pick **Developer mode** from the plus menu and select WhatSetter.

## Gemini CLI

Gemini CLI discovers the OAuth flow by itself for remote HTTP servers:

```bash
gemini mcp add --transport http whatsetter https://mcp.whatsetter.com/mcp
```

To use the key directly:

```bash
gemini mcp add --transport http --header "Authorization: Bearer ws_live_…" whatsetter https://mcp.whatsetter.com/mcp
```

## Codex CLI

With the key in an environment variable:

```bash
export WHATSETTER_API_KEY="ws_live_…"
codex mcp add whatsetter --url https://mcp.whatsetter.com/mcp --bearer-token-env-var WHATSETTER_API_KEY
```

Or with OAuth:

```bash
codex mcp add whatsetter --url https://mcp.whatsetter.com/mcp
codex mcp login whatsetter
```

The equivalent in `~/.codex/config.toml`:

```toml
[mcp_servers.whatsetter]
url = "https://mcp.whatsetter.com/mcp"
bearer_token_env_var = "WHATSETTER_API_KEY"
```

## The 66 tools

Each tool needs the scope of the endpoint it calls. A key without that scope makes the tool answer `insufficient_scope`.

| Tool | Scope | What it does |
|---|---|---|
| `whoami` | none | Workspace, key name and granted scopes. Call it first. |
| `list_leads` | `leads:read` | List leads, filterable by status, campaign, channel, phone, your `external_reference`, source, tracked link, date. |
| `get_lead` | `leads:read` | One lead with status, tags, owner, next action, counters. |
| `update_lead` | `leads:write` | Change status, tags, `assigned_to`, `next_action_at`, `next_action_label`, `deal_status`, `lost_reason`. |
| `handoff_lead` | `leads:write` | Stop the AI on this conversation and hand it to a human. |
| `resume_lead` | `leads:write` | Give the conversation back to the AI. |
| `list_lead_notes` | `leads:read` | Notes on a lead, newest first. |
| `add_lead_note` | `leads:write` | Add a note to a lead. |
| `list_conversations` | `conversations:read` | Inbox on WhatsApp, Instagram and Messenger, most recent activity first: who answers each one, which ones need a reply, what the triage read. Filter by `channel`, `needs_reply`, `triage`. |
| `get_conversation_messages` | `conversations:read` | Full message history of one lead. |
| `send_message` | `messages:send` | **Sends a real message** to a lead already in conversation, on its channel. WhatsApp: anti-ban rules. Instagram and Messenger: within 24 hours of the person's last message only. An automatic `Idempotency-Key` applies. |
| `send_whatsapp_message` | `messages:send` | The same tool as `send_message`, under its first name. |
| `list_lists` | `lists:read` | Your contact lists. |
| `create_list` | `lists:write` | Create an empty list. With `keep_open`, a finished list starts again by itself when contacts come in. |
| `import_leads` | `lists:write` | Push up to 500 contacts into a list. No message is sent by the import itself. |
| `list_campaigns` | `campaigns:read` | Campaigns with status, channels and connected number. |
| `pause_campaign` | `campaigns:write` | Pause an active campaign. |
| `resume_campaign` | `campaigns:write` | Resume a paused campaign. Sending restarts. |
| `add_campaign_lead` | `messages:send` | **Sends the first message** to an opt-in lead through the campaign pipeline. |
| `list_bookings` | `bookings:read` | Meetings booked by the agent. |
| `list_groups` | `groups:read` | Tracked WhatsApp groups. |
| `get_group` | `groups:read` | One group with counts, invite link, AI mode. |
| `list_group_members` | `groups:read` | Members of a group, active or left. |
| `list_group_messages` | `groups:read` | Transcript of a group. |
| `list_group_events` | `groups:read` | Join and leave events of a group. |
| `list_webhooks` | `webhooks:manage` | Your subscriptions, without secrets. |
| `create_webhook` | `webhooks:manage` | Subscribe an HTTPS endpoint. The secret is returned once. |
| `delete_webhook` | `webhooks:manage` | Remove a subscription. |
| `test_webhook` | `webhooks:manage` | Post a signed test event to your endpoint. |
| `list_blocked_contacts` | `blocklist:manage` | Blocked numbers and dial prefixes. |
| `block_contact` | `blocklist:manage` | Block a number or a dial prefix. The agent stops replying to it. |
| `unblock_contact` | `blocklist:manage` | Remove a block. |
| `list_team_members` | `team:read` | Members of the workspace, to assign leads. |
| `list_links` | `links:read` | Tracked links with click counts. |
| `get_link` | `links:read` | One link with its 30-day stats. |
| `get_agent_prompts` | `prompts:read` | Everything an agent runs on: its prompts, what is live, its variables and its knowledge base. |
| `get_agent_prompt` | `prompts:read` | One text of an agent. |
| `update_agent_prompt` | `prompts:write` | **Changes a prompt, live on the agent's next message.** New version for the conversation and the first message. Refused while a draft saved in the dashboard waits, until you choose what to do with it. |
| `list_prompt_versions` | `prompts:read` | History of a prompt, with status and author. |
| `get_prompt_version` | `prompts:read` | One version with its full text. |
| `compare_prompt_versions` | `prompts:read` | What a version changes compared to another one, or to the text in service, as a diff. |
| `restore_prompt_version` | `prompts:write` | **Puts an earlier version back in service**, live on the next message. |
| `list_knowledge_bases` | `knowledge:read` | Knowledge bases with their sources and linked agents. |
| `get_knowledge_base` | `knowledge:read` | One base with each website, each file (and whether its text is editable) and its answers count. |
| `search_knowledge` | `knowledge:read` | The passages the agent is handed for a message. Same search as at reply time. |
| `list_knowledge_answers` | `knowledge:read` | The question and answer pairs of a base. |
| `add_knowledge_answer` | `knowledge:write` | Add an answer. The agents use it on their next reply. |
| `update_knowledge_answer` | `knowledge:write` | Correct an answer. The previous text is not kept. |
| `delete_knowledge_answer` | `knowledge:write` | Remove an answer. |
| `get_knowledge_file` | `knowledge:read` | The whole text of a file. For a PDF or a Word file, the text the agent holds. |
| `add_knowledge_file` | `knowledge:write` | Add a text file. It is read at once. |
| `update_knowledge_file` | `knowledge:write` | Rewrite a text file: one place with targeted edits, or the whole text. The agents know it on their next reply. |
| `delete_knowledge_file` | `knowledge:write` | Remove a file of any kind. |
| `list_instagram_accounts` | `instagram:read` | The connected Instagram accounts: what each one may do, its Facebook Page, its agent, its triage, the pause after a person's reply. |
| `list_instagram_posts` | `instagram:read` | Instagram posts of the last 7, 30 or 90 days: views against the account's average, then what they brought, down to meetings booked. |
| `get_instagram_best_times` | `instagram:read` | The days and hours the account's posts do best, and the next three moments to post. |
| `get_instagram_stats` | `instagram:read` | What the automations did over 7, 30 or 90 days against the period before, by day, automation and post. |
| `list_scheduled_instagram_posts` | `instagram:read` | The posts planned through WhatSetter, with their state and why one failed. |
| `get_scheduled_instagram_post` | `instagram:read` | One planned post: its state, its link once out, its copy on the Facebook Page. |
| `schedule_instagram_post` | `instagram:write` | **Publishes publicly on Instagram**, now or at a time: a photo, a carousel, a reel (or a trial reel) or a story, with an optional first comment and comment automation. |
| `update_scheduled_instagram_post` | `instagram:write` | **Can publish**: change a planned post's caption, time, first comment, automation or options; `publish_at: null` publishes it within a minute. |
| `cancel_scheduled_instagram_post` | `instagram:write` | Cancel a planned post. It does not go out. |
| `list_instagram_automations` | `instagram:read` | The comment, story and message automations, with what they did. |
| `create_instagram_automation` | `instagram:write` | Create an automation, off by default. **Switched on, it writes to real people.** |
| `update_instagram_automation` | `instagram:write` | Change an automation, or switch it on or off. |
| `delete_instagram_automation` | `instagram:write` | Delete an automation and its counters. |

Five tools can reach a real person: `send_message` (and its first name `send_whatsapp_message`) and `add_campaign_lead` send a message, and `create_instagram_automation` / `update_instagram_automation` switch on an automation that writes to everyone who comments its words. Three publish or withdraw on Instagram: `schedule_instagram_post`, `update_scheduled_instagram_post` and `cancel_scheduled_instagram_post`. `resume_campaign` restarts a campaign's own sending. `test_webhook` posts to your server, not to a contact.

Two tools change what a live agent says from its next message: `update_agent_prompt` and `restore_prompt_version`.

## Explain and fix a reply

Ask the assistant why an agent said something. It reads three things in a row and quotes what explains the reply:

| Step | Tool | What it gives |
|---|---|---|
| 1 | `get_conversation_messages` | The exchange. Each message says what wrote it: the first message, a reply, a follow-up or a person. |
| 2 | `get_agent_prompts` | The prompt the agent ran on, with the values of its variables. |
| 3 | `search_knowledge` | The passages the agent was handed from its knowledge base for that message. |

Then ask for the fix. The assistant proposes the smallest change, shows it to you, and applies it with `update_agent_prompt`, `add_knowledge_answer` or `update_knowledge_file` once you agree. `restore_prompt_version` undoes a prompt change, and `compare_prompt_versions` shows what changed between two versions.

If a draft saved in the dashboard waits on the prompt, the assistant tells you before changing anything: the agent does not read that draft, and you choose which text to start from.

The server sends these steps to the assistant when it connects, so you do not have to spell them out. Details in [Agent prompts](/developers/guides/prompts/) and [Knowledge bases](/developers/guides/knowledge/).

## Example prompts

- "Show me the leads qualified this week and who owns each one."
- "Assign every unassigned qualified lead to Julien and set a next action for Monday 9am called Call back."
- "Block the +91 prefix, reason: out of market."
- "Which tracked link brought the most leads in the last 30 days?"
- "Import these 40 contacts into a new list called Webinar September." (paste the contacts)
- "Pause the Acme France campaign."
- "Summarize the conversation with +33612345678 and add a note with the summary."
- "Which Instagram messages are waiting for an answer from me? Draft a reply to each, I will check them before you send."
- "Create an automation, switched off, that sends the buyer's guide to everyone who comments GUIDE on my next posts."
- "Why did my agent Julien tell +33612345678 that the trial costs 12 euros? Find the cause and propose a fix."
- "In Julien's conversation prompt, add a rule: never give a price before the lead says what they need. Show me the change first."

## Safety

- Read tools are marked read-only. `send_message`, `send_whatsapp_message`, `add_campaign_lead`, the Instagram automation tools and the ones that publish are marked as side-effecting: a well-behaved client **asks you before calling them**. Read the message before you approve it, it goes to a real person.
- `update_agent_prompt` and `restore_prompt_version` are marked the same way: the change is live on the agent's next message, so read it before you approve. Every prompt change is a new version, and a restore brings the previous one back.
- The assistant can only do what the key allows. Give an assistant a **Custom** key with read scopes if it should not send anything.
- Every `/mcp` session is bound to the key that opened it: a stolen session id is useless without the key.
- **Revoke the key** in **Settings**, then **API & MCP**, and everything stops: REST calls, OAuth sessions and direct-bearer sessions alike.

## Related

- [Authentication and permissions](/developers/authentication/)
- [Errors, limits and idempotency](/developers/errors/)
- [Use these docs with AI assistants](/developers/ai-assistants/)
