Connect an AI assistant (MCP)

InstantCampaign runs a Model Context Protocol (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

Read

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`, `get_campaign_performance`	Campaigns with status; one campaign’s emails, sends, audience and sender setup; send, open and click statistics, how many recipients the cadence policy held back, and `smartTiming` (smart-timed vs fixed-time results)
`get_structured_email_data`	What the agent-readable layer adds to a campaign’s or template’s email for AI inboxes: the facts it states (offer, event, order and shipment, main link), the key-facts line and the schema.org JSON-LD, rendered for a sample recipient
`get_campaign_plan`, `get_ab_test_results`	The strategist’s plan for a campaign, and A/B test outcomes
`get_synthetic_panel_results`	The last synthetic-panel screening run for a campaign: per-variant screening scores, spread and reasons from personas built on audience aggregates. A screening aid, not a prediction; it cannot start a run
`get_campaign_proposals`	This week’s proposed campaigns (accepting one happens in the app)
`list_journeys`, `get_journey`	Automations with status and totals; one automation’s trigger, steps (with each Send email step’s AI personalisation setting and generated / reused / fallback counts) and the contacts currently in it by status
`get_audience_summary`	Contact totals by status, lists and segments with their sizes, and how many contacts sit in each predictive-score tier (Champion, Loyal, Promising, New, At risk, Dormant) from the last daily scoring run. Aggregates only
`list_lists`, `get_list`	Lists with member counts and settings; one list’s members by subscription status
`list_segments`, `get_segment`	Segments with their size and rebuild state; one segment’s rules
`list_custom_fields`	The custom contact fields and their types, by key. A field marked sensitive is listed as `sensitive: true` without its options or description
`estimate_audience`	How many sendable contacts a choice of lists and segments (minus exclusions) reaches, de-duplicated, as the send wizard counts it
`list_forms`, `list_landing_pages`	Signup forms with their list and submissions; landing pages with their public URL and views
`list_synced_blocks`	Synced blocks with their description, how many templates use each and when each last changed; never the block content
`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?”. Rows name the recipient’s domain and contact id, never the address
`get_analytics_overview`, `get_analytics_breakdown`, `get_engagement_hours`	Email analytics for a period; the same broken down by domain, campaign, journey, link, client or device; when the audience reads, by weekday and hour
`get_web_analytics`	Website traffic from the snippet, plus identified-across-visits and consent counts (never a visitor id)
`get_conversion_attribution`	The conversion attribution report: goals credited to the channel, source and attribution rule of the visit that brought the converter and to the campaign send or automation step that reached them, with how each attribution rule performed
`list_reports`, `get_report_run`	Scheduled client reports: cadence, sections, filters and recipient count (never the addresses), next send and the latest run; one run’s period, status, headline numbers with changes, and its signed online link. No tool sends a report
`get_organization_overview`	For an agency organization the workspace belongs to: one row per client workspace with plan, contacts, sends, opens and clicks with changes, deliverability health, trust review (organization owners and admins), last campaign and report, and the at-risk share, plus the portfolio alert counts of the last 7 days. Only organization members; it reads nothing outside the organization’s workspaces
`get_organization_anomalies`	For an agency organization the workspace belongs to: the rule-based portfolio alerts of its client workspaces (high bounce or complaint rate, unsubscribe spike, engagement drop, DMARC failures up, send volume collapsed) with the value, the four-week baseline and the threshold. Read-only; only organization members
`get_account_export_status`	The workspace’s full account exports (Settings → Data export): status, when each was requested and finished, size, how many contacts, templates, journeys and other items it holds, and when the download expires. The archive is downloaded in the app only
`search_help`	Search the help documentation (these pages) and get the best-matching sections with links
`get_ads_overview`	Ad Studio spend, clicks, conversions and leads, per campaign, with paid site visits and lead follow-up
`get_deliverability_status`	Sending domains: verification, DNS drift, warm-up progress and the latest reputation verdict
`get_sending_setup`	Send policies, delivery routes and sender profiles (labels only, no addresses)
`get_cadence_policy`	The per-recipient cadence policy: on or off, the weekly cap, fatigue and dormant rules, cooldowns, and how many contacts chose their own frequency (counts only)
`get_lift`	Holdout lift: the conversion rate of contacts who were sent marketing email vs the control group who were not, for a period, one campaign or one journey, with the difference, its 95% interval, relative lift and a p-value. Aggregates only; below 100 contacts per group it says there is not enough data
`get_hygiene_summary`	List hygiene: stored, active, unsubscribed/bounced/complained, sunset and in-re-engagement contact counts, plus the sunset policy and its last run (counts only, no addresses)
`get_accessibility_report`	A campaign’s accessibility report: for each distinct email it was sent with, the WCAG 2.1 AA and dark-mode score (0–100), errors, warnings and info counts, counts per rule and category scores. Never the HTML or excerpts; warnings only, nothing blocks a send. Essential plan and above
`get_push_summary`	Web push results: for a campaign or a journey, notifications delivered, clicked, expired and failed with the click rate; for the workspace, live / matched / anonymous subscribers, per-site counts and the latest campaigns and journeys that sent push. Aggregates only, never an endpoint or a contact. No tool sends a push
`get_replies`	Replies captured from recipients: counts per classification (person, automatic reply, bounce notice, unsubscribe request) for a campaign, an automation and its versions, or the campaigns and automations with replies in the last N days, plus the ids of the latest replies, whether each was forwarded and what it did (automation runs ended, unsubscribed). Never the reply text, subject or address. Essential plan and above
`get_event_stream_status`	The event stream that ships every send, delivery, bounce, open, click, unsubscribe and conversion to your S3 bucket, CDP or HTTPS endpoint: destination kind, on or paused and why, events waiting, lag, delivered and dropped counts, last error. Never the address or credentials. Pro plan and above
`get_poll_results`	Poll block results for a campaign or an automation: per poll, the question, the number of answers, when the last vote came in, and each answer’s label, votes and share. One answer per person per poll. Counts and labels only
`get_setup_guide`	The “Getting started” checklist as the app derives it: what is done and what to do next
`get_brand_config`, `get_usage_report`	Brand colours, fonts and voice; this month’s usage and each plan allowance

Write

Tool	What it does
`generate_copy`	Email copy in your brand voice
`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 description, including the steps of a flow you are rebuilding from Klaviyo, ActiveCampaign, Mailchimp or Kit. It is a draft; nothing activates
`attach_ads_to_campaign`	Stage matching paid ads for a campaign plan: an ad audience from the recommended list or segment on Meta and/or Google Ads (optional Meta lookalike), one generated image and a draft ad campaign per platform. Nothing is published or spends; the image uses 15 AI credits
`draft_quiz`	Draft a preference quiz for a signup form from a brief: 2–4 questions whose answers write your non-sensitive custom-field options, yes/no tags or the contact’s email frequency, plus a result message. Returns the draft only, nothing is saved; uses 3 AI credits. Essential plan and above
`create_list`	Create an empty list
`create_segment`	Create a segment from conditions (profile fields, custom fields by key, acquisition channel (`acquisitionChannel` equals `ai` = contacts who signed up during an AI-assistant visit), list status, email engagement across all email or one campaign or automation, including “in the last N days”, forms, events, goals, predictive scores and tiers), with AND/OR groups. Membership builds in the background
`upsert_contact`	Create or update a contact by email, with custom fields and the lists to subscribe it to
`add_contact_to_list`, `remove_contact_from_list`	Change one contact’s membership of one list
`unsubscribe_contact`	Unsubscribe a contact from all marketing email (cascades to every list)
`record_event`	Record a custom event or goal (a purchase, a signup, …) for a contact

Every tool is annotated for MCP clients: a title, and whether it only reads (readOnlyHint) or makes a hard-to-undo change (destructiveHint, set on remove_contact_from_list and unsubscribe_contact). 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. Adding a contact to a list or recording an event can enrol the contact in an automation that already listens for it, exactly as the API would.

An assistant that follows the MCP authorization flow — Claude Desktop, Cursor and others — can connect with a sign-in window instead of an API key:

Add the server URL https://instantcampaign.ai/api/mcp. The assistant is told where to sign in (the server answers with the standard discovery documents at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server) and registers itself as a client.
Your browser opens InstantCampaign’s consent page. Pick the workspace, review the permission (mcp), and click Allow access.
The assistant holds a token bound to the MCP server only — it cannot be used against the rest of the API — refreshed automatically for 90 days.

Because a self-registering assistant has not been reviewed by InstantCampaign, the consent page marks it Unverified app and shows where it will send you back. Only continue if you started the connection from software you trust. You can see and disconnect the connection under Settings → Developers → Connected apps. An assistant that does not support this flow can still connect with an API key that has the MCP permission.

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. The tools that take an email address (check_contact_status, upsert_contact, add_contact_to_list, remove_contact_from_list, unsubscribe_contact, record_event) look up an address you already have and answer with the contact’s id and status, never the address. Custom fields marked sensitive are withheld from every tool output, and rule values that use them read [sensitive]. See AI data privacy.

Connect

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.

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:

claude mcp add --transport http instantcampaign https://instantcampaign.ai/api/mcp \
  --header "Authorization: Bearer ic_your_key_here"

Try it

Ask the assistant something like “How did my last three campaigns perform?” It should call list_campaigns and get_campaign_performance.

Limits

Images: the MCP server has no stand-alone image tool. To generate a marketing image, use AI Studio, the email builder’s AI image tools or Spark in the app.
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, and AI tools use AI credits at the same cost as in the app: generate_copy and create_journey_from_brief use 1 credit each, draft_quiz uses 3, attach_ads_to_campaign with a matching image uses 15, create_template_draft and duplicate_template count as templates, and upsert_contact counts against the contact allowance when it creates a contact. When a quota is used up or the workspace has no AI credits left, 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.

Reviewing what the assistant did

Every change an assistant makes — each call to a Write tool above — is listed in Settings → Developers → Agent activity, newest first, with:

the app (for an assistant connected by sign-in) or the API key that made it,
the tool it called and what it created or changed, with a link to open it (the campaign’s plan page, the template in the builder, the automation, the segment, the contact),
a link to the full request in the API log.

Campaigns, templates and automations an assistant creates are marked Needs review. For each one you can:

Mark reviewed — you have looked at it. Nothing else changes: to send the campaign you still approve its plan, to use the template you still approve it in review, and to start the automation you still activate it.
Discard — if it is still an untouched draft (a campaign never sent, a draft template no campaign uses, a draft automation nobody has entered), it is deleted. Anything else is kept and only marked discarded.

Owners and admins get a notification when an assistant drafts something for review. Filter the list by status, source and app or key. Viewing the page needs the API key permission; Mark reviewed and Discard need the content approval permission.

Agent policy

At the top of the same page:

Setting	Default	What it does
Allow agents to make changes	On	Off: every Write tool returns an error saying agent writes are turned off. Read tools keep working.
Agent drafts need review	On	Off: campaigns, templates and automations an assistant creates are still listed, but not marked Needs review. They are drafts either way.

Changing the policy needs both the API key permission and the content approval permission. Lists, segments, contacts and events are recorded but never wait for review. Every MCP call, reads included, is also recorded in Settings → Developers → API log under the /api/mcp path, with the tool call as the request body. See 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
Tool error “AI agents may not make changes in this workspace”	Agent writes are turned off in the agent policy	Turn Allow agents to make changes back on under Settings → Developers → Agent activity