# 🔌 MCP server: create creatives with your AI assistant

The Collective Audience™ MCP server lets your AI assistant (Claude, Cursor, or any client compatible with the Model Context Protocol) create interactive creatives directly in your Collective Audience account: questions, carousels, duels, quizzes, surveys, personality tests, forms, games and canvases, with your branding.

You describe what you want in plain language, the assistant builds the creative, gives you a preview link, and saves it to your Desk once you validate it.


:::info
**Beta.** The MCP server is in beta. Tools and fields can evolve. Always review the preview before saving a creative to your Desk.

:::

# What you need

* A Collective Audience™ account with access to the [Desk](https://desk.collectiveaudience.co).
* An **API key** for your account (see step 1).
* An AI client that supports **remote MCP servers over HTTP with a custom header**: Claude Code, Claude Desktop, Cursor, VS Code, or any equivalent.
* Optional: a client that can run shell commands (Claude Code, Cursor, Claude with code execution) if you want to upload your own images through the assistant.

# Step 1: create an API key


1. In the Desk, go to [Settings > API KEYS](https://desk.collectiveaudience.co/settings/account/api-keys).
2. Click **+ New** and name the key after its use, for example `MCP - Claude - Marketing team`.
3. Set a **number of days before revocation** (we recommend 90 days or less).
4. Copy the key value.

See [Key management](https://outline.collectiveaudience.co/doc/key-management-FGsdrQOF9T) for details on creating, retrieving and revoking keys.


:::warning
The API key gives access to your account. Create one key per person or tool, never paste it in a chat or a shared document, and revoke it immediately if it leaks.

:::

# Step 2: connect your AI client

| Setting | Value |
|---------|-------|
| Server name | `collective-audience` (any name works) |
| Transport | Streamable HTTP |
| URL     | `https://mcp.collectiveaudience.co/mcp` |
| Header  | `Authorization: Bearer <YOUR_API_KEY>` |

## Claude Code

```bash
claude mcp add --transport http collective-audience https://mcp.collectiveaudience.co/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"
```

Run `claude mcp list` to check the server is connected.

## Claude Desktop

Claude Desktop connects to remote servers with a header through `mcp-remote` (requires Node.js). Open **Settings > Developer > Edit Config** and add:

```json
{
  "mcpServers": {
    "collective-audience": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.collectiveaudience.co/mcp",
        "--header", "Authorization: Bearer ${CAUD_API_KEY}"
      ],
      "env": { "CAUD_API_KEY": "<YOUR_API_KEY>" }
    }
  }
}
```

Restart Claude Desktop. The Collective Audience tools appear in the tools menu.

## Cursor

In `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "collective-audience": {
      "url": "https://mcp.collectiveaudience.co/mcp",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}
```

## Other clients

Use the values from the table above. If your client cannot send a custom `Authorization` header, it cannot connect yet: contact your Collective Audience™ account manager.

# Step 3: check the connection

Ask your assistant:

> Which Collective Audience account are you connected to?

It calls `caud-account-info` and answers with your account name. A `401 Missing Authorization header` or `401 Invalid API key` error means the header is missing, mistyped, or the key is revoked.

# How it works


1. **You brief the assistant**: format, brand, message, product page URL, images.
2. **The assistant creates the building blocks** (questions, choices, exits, forms...) and wraps them in a creative with your branding.
3. **It gives you a preview link** (`caud-generate-preview-url`). Nothing is visible in your Desk yet.
4. **You review** the preview on desktop and mobile, and ask for changes (:warning: the generated preview is available for just 30 minutes, if you like it, don’t forget to ask for save in the Desk) 
5. **Once you validate, the assistant saves the creative to your Desk** (`caud-save-to-desk`). From there you edit, schedule and distribute it as usual.


:::tip
Ask the assistant to **wait for your validation before saving**. A saved creative is in your Desk for real: you can edit or delete it there, but not through the MCP server.

:::

# Available tools

| Tool | What it does |
|------|--------------|
| `caud-account-info` | Shows the account the key is linked to |
| `caud-create-question` / `caud-update-question` / `caud-fetch-question` | Question, carousel and duel formats |
| `caud-create-quiz` (+ update, fetch) | Quizzes with right / wrong answers and score end screens |
| `caud-create-survey` (+ update, fetch) | Multi-question surveys, with optional branching |
| `caud-create-personality` (+ update, fetch) | Personality tests (profiles mapped to answers) |
| `caud-create-form` (+ update, fetch) | Lead forms   |
| `caud-create-game` (+ update, fetch) | Contests (random draw or instant win) with a form and an optional quiz |
| `caud-create-canvas` (+ update, fetch) | Canvas: image, title and call to action |
| `caud-create-exit` (+ update, fetch) | Links and calls to action (external URL, button or direct click-out) |
| `caud-create-optin` (+ update, fetch) | Opt-in blocks |
| `caud-create-content` (+ update, fetch) | The creative itself: chains the formats above and applies branding |
| `caud-upload-local-media` | Uploads an image (logo, packshot, background) to your media library |
| `caud-generate-preview-url` | Returns a preview link |
| `caud-save-to-desk` | Saves the creative to your Desk |

# Example prompts

> Create a product carousel for our coffee machines with these 8 images. Navy background, logo at the top, each card opens the product page. Show me the preview before saving.

> Build a 3-question quiz about our new summer collection from https://example.com/summer, with a score end screen, in our brand colors.

> Turn this personality test into a contest: after the result, users can enter their email to win a voucher. Draft only, don't save.

# Tips for better results

* **Give a source.** Paste the product or campaign page URL: the assistant should only use facts from it.
* **Send your assets.** Logo, packshots and key visuals give much better results than generated images. Square images work best for carousels and duels.
* **State your branding**: main colors, font, logo position, tone (formal "vous" or informal "tu").
* **Say where each click should go.** For a carousel where each card opens a product page, give one URL per product.
* **Contests and forms**: provide the game rules, the organizer, the dates and your privacy notice. Only collect the data you need, and keep marketing consent optional and unticked.

# Data and privacy

* The MCP server only acts on the account linked to the API key.
* What you send to your AI assistant (briefs, images, URLs) is processed by your AI provider under your agreement with them. Do not include personal data (customer lists, emails) in your prompts.
* Every creative made through the MCP server is marked as AI-assisted in its settings.

# Troubleshooting

| Symptom | Fix |
|---------|-----|
| `401 Missing Authorization header` | The client is not sending the header. Check the config syntax and restart the client. |
| `401 Invalid API key` | Key mistyped, revoked or expired: create a new one. |
| Tools do not appear | Restart the client; check the URL ends with `/mcp`. |
| Image upload fails | Your client needs to run shell commands (e.g. Claude Code). Otherwise, upload the image in the Desk media library and give the assistant its URL. |
| The creative looks wrong in the preview | Describe the problem to the assistant and ask it to rebuild the creative before saving. |

Need help? Contact your Collective Audience™ account manager.