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

# Connect an AI assistant (MCP)

> Let Claude, an IDE or an agent read your templates, campaigns and analytics and draft new work in your workspace through the InstantCampaign MCP server.

InstantCampaign runs a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. An MCP-capable AI assistant can use it to look up campaign results, check a template before a transactional send, write copy in your brand voice or draft a campaign, all inside your workspace.

## What the assistant can do

| Tool                                          | What it does                                                                                                                |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `get_workspace_overview`                      | Counts of templates, campaigns, contacts, lists and segments, the contact status breakdown, and the 5 most recent campaigns |
| `list_templates`, `get_template`              | Browse and read templates                                                                                                   |
| `preview_template`                            | Render a template with a payload (or its sample data) and list the variables it reads and any that are unresolved           |
| `list_campaigns`, `get_campaign_performance`  | Campaigns with status, and their send, open and click statistics                                                            |
| `get_campaign_plan`, `get_ab_test_results`    | The strategist's plan for a campaign, and A/B test outcomes                                                                 |
| `get_campaign_proposals`                      | This week's proposed campaigns (accepting one happens in the app)                                                           |
| `get_audience_summary`                        | Contact totals by status, and lists and segments with their sizes. Aggregates only                                          |
| `check_contact_status`                        | Whether an email address is a contact, its status and how many lists it is on                                               |
| `get_message_log`                             | Recent individual emails with delivery status, opens and clicks, to answer "did X get the email?"                           |
| `get_analytics_overview`, `get_web_analytics` | Email analytics and website traffic                                                                                         |
| `get_brand_config`, `get_usage_report`        | Brand colours, fonts and voice, and this month's usage per quota                                                            |
| `generate_copy`, `generate_image`             | Email copy in your brand voice, and marketing images                                                                        |
| `create_template_draft`, `duplicate_template` | Create a new draft template, or copy an existing one                                                                        |
| `create_campaign`                             | Create a campaign from a brief. The strategist writes the emails and plan                                                   |
| `create_journey_from_brief`                   | Draft an automation from a one-sentence description                                                                         |

<Note>
  The assistant cannot send email or start anything. Campaigns created through MCP wait for someone to approve the plan in the app, and journeys are created as drafts that never activate by themselves.
</Note>

## Privacy

MCP clients pass tool results to their own AI models, so every result goes through the same privacy filter as the in-app assistant. Contact tools return aggregates, statuses and ids, never lists of people. Every output passes a redaction layer that removes email addresses, names, phone numbers and postal addresses. For example, `check_contact_status` looks up an address you already have but never returns it.

## Connect

<Steps>
  <Step title="Create a key for the assistant">
    In **Settings → Developers → API Keys**, click **Create New Key**. Name it after the assistant, and under **Permissions** tick only **AI assistant (MCP)**. That key can then use the MCP server but not the rest of the API. See [API keys](/guides/developers/api-keys).
  </Step>

  <Step title="Add the server to your client">
    Configure an MCP server with the **Streamable HTTP** transport:

    * URL: `https://instantcampaign.ai/api/mcp`
    * Header: `Authorization: Bearer ic_your_key_here`

    For example, in Claude Code:

    ```bash theme={null}
    claude mcp add --transport http instantcampaign https://instantcampaign.ai/api/mcp \
      --header "Authorization: Bearer ic_your_key_here"
    ```
  </Step>

  <Step title="Try it">
    Ask the assistant something like "How did my last three campaigns perform?" It should call `list_campaigns` and `get_campaign_performance`.
  </Step>
</Steps>

## Limits

* **Rate limit:** 60 requests per minute per workspace. Beyond that the server answers `429`.
* **Plan quotas:** tools count against your plan's monthly quotas, as they do in the app. `create_campaign` counts against campaign generations, `generate_copy` and `create_journey_from_brief` use AI text generations, `generate_image` uses AI image generations, and `create_template_draft` and `duplicate_template` count as templates. When a quota is used up, the tool returns an error saying so.
* **Transport:** the server answers each request with plain JSON. It does not open server-initiated streams and issues no session id. Clients that support Streamable HTTP work as is.

## Seeing what the assistant did

Every MCP call is recorded in **Settings → Developers → API log** under the `/api/mcp` path, with the tool call as the request body. See [API request log](/guides/developers/api-request-log).

## Troubleshooting

| Error                                      | Cause                                                                    | Fix                                                    |
| ------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------ |
| `401 Invalid or missing API key`           | The header is missing, or the key was deleted or has expired             | Check the `Authorization` header in your client config |
| `403` "This API key lacks the "mcp" scope" | The key was created with other scopes and without **AI assistant (MCP)** | Create a key with the MCP scope                        |
| `429 Rate limit exceeded`                  | More than 60 calls in a minute                                           | Wait a minute; agents that loop quickly can hit this   |
| Tool error about a quota being used up     | A monthly plan quota is spent                                            | Upgrade the plan, or wait for the next month           |