MCP tools
The hosted MCP server offers the same tools that power Spreeflo's in-app AI, minus the actions that only a person can take in the app. A connection that can make changes is offered 77 tools: 40 that only read, 35 that change your workspace, and 2 that save a chart or a CSV export. A read-only connection is offered 42: the reads plus the chart and export tools.
This page is a map, not a specification — your client reads the full schema and description of each tool when it connects. Descriptions here are deliberately short.
Warning: Every write tool on this page applies immediately to your live workspace. There's no staging step and no approval queue — see confirmation settings.
Reading and lookups
39 read-only tools. None of these change anything in your workspace.
| Area | Tools |
|---|---|
| Workspace & audiences | get_business_profile, list_audiences |
| Campaigns, broadcasts & journeys | list_campaigns (broadcasts included), list_journeys, get_campaign, get_broadcast, get_sequence — get_broadcast returns a broadcast's settings and emails, what still blocks it from sending, and how many contacts it would reach. |
| Segments | list_segments, get_segment_definition, get_segment_preview — the preview returns the member count and a sample of who a segment currently targets. |
| Contacts, notes, tags & attributes | list_contacts, get_contact, list_contact_notes, list_tags, get_tag, list_contact_attributes — contact notes are your team's internal notes on a contact, and say who wrote each one. They're never sent to the contact. |
| Email templates | list_email_templates, get_email_template, get_email_template_structure |
| Web push | list_webpush_templates, get_webpush_template |
| Forms | list_forms, get_form, get_form_analytics (views → starts → submissions funnel), get_form_summary (per-question response breakdown), list_form_embeds |
| Sender identities & domains | list_email_identities, get_email_identity, list_domain_identities, get_domain_identity |
| Website & event data | list_pages, list_link_clicks, list_custom_events, list_custom_event_properties |
| Performance | get_campaign_performance, get_webpush_performance, get_events_summary |
| Reference | read_help_article (Spreeflo help-centre articles), read_format_doc (document format specs — see Working with documents) |
The fortieth read-only tool, get_email_template_preview, renders an email for the preview that some AI clients display inside the chat. Only that preview calls it.
Creating assets
15 tools. Everything they create is real and lives in your workspace — but nothing they create is live.
create_campaign_sequence, create_journey_sequencecreate_broadcast — a one-off email to an audience, with optional follow-ups. It's always created as a draft create_segmentcreate_email_template, create_webpush_templatecreate_form, create_form_embed, create_popup_embed (Pro only — a free trial counts) create_tag, create_contact_attributeregister_domain_identity, create_email_identity — the domain is created in a pending state and the tool returns the DNS records someone has to add. Admin only import_contacts_csv — bulk import from CSV content, where the header row uses attribute keys and email is required. It can also add or remove tags create_contact_note — an internal note on one contact. Your team sees it on the contact's Notes tab, marked as written by an AI agent; it's never sent to the contact Note: A campaign, journey, broadcast, or form created over MCP is not live. It exists as a draft or unpublished asset, and a person starts, sends, or publishes it in the Spreeflo app.
Editing existing assets
15 tools. Each applies the moment it's called.
| Tool | What it changes |
|---|---|
update_sequence | The steps (node graph) of a campaign or journey. DRAFT or PAUSED only. |
update_campaign | Name, settings, and UTM parameters — plus targeting, for DRAFT campaigns only. |
update_broadcast | A draft broadcast's settings and follow-ups. Only what's passed changes. Its main email is edited with update_email_template. |
update_segment | A segment's name and definition. |
update_email_template | An email template's builder document. |
update_webpush_template | A web push template. |
update_form | A form's draft questions and settings. |
update_form_embed | An inline form embed. |
update_popup_embed | A popup embed. Pro only. |
rename_tag | Renames a tag. |
tag_contacts | Adds or removes tags on one contact by name. Unknown tags being added are created. |
update_contact | A contact. This is a partial edit — only the fields you pass change. |
update_contact_note | Rewrites a contact note an AI agent wrote. A note written by a team member can't be changed — add a new one instead. |
update_email_identity | The display name of a sender address. The address itself can't be changed. Admin only. |
update_business_profile | The workspace business profile. |
Every tool is named for what it does, verb first — create_form, update_form, pause_campaign — because that's exactly what happens when it's called.
Lifecycle and duplication
pause_campaign — pauses an ACTIVE or SCHEDULED campaign or journey. Contacts already part-way through hold their place and continue if a person resumes it in the app. unschedule_broadcast — takes a scheduled broadcast that hasn't started sending back to a draft, so nothing goes out at the scheduled time. duplicate_campaign, duplicate_email_template, duplicate_webpush_template — copies are always created as drafts. Pausing and unscheduling are available but starting, resuming, sending and scheduling are not, and that asymmetry is deliberate: an agent can stop a send, never begin one.
Charts and exports
Two tools for turning workspace data into something you can share. They save a file to your workspace's file store and change no workspace data, so read-only connections get them too:
render_chart — turns a Vega-Lite spec into a stored chart and returns its URL.export_form_responses_csv — the same flattened CSV as the in-app export, capped at 10,000 rows per export.How the tools behave
Read-only connections and team roles
Which tools your client is offered depends on how the connection was approved and on your role in the workspace, re-checked on every call:
render_chart and export_form_responses_csv.register_domain_identity, create_email_identity and update_email_identity. This mirrors what each role can do in the Spreeflo app.
Paging through lists
List tools return one page at a time. The first call leaves out cursor; each page returns a nextCursor, and passing it back as cursor, with the same filters, fetches the next page. When nextCursor is null there's nothing more. limit sets the page size, from 1 to 100 (25 by default); list_contact_notes returns at most 50 notes a page.
What a write returns
A write that succeeds returns { applied: true, result }, where result is what was created or changed. A write that fails returns an error saying why — a missing field, an id that wasn't found and which tool lists valid ones, or a document that broke a format rule. If the error is an unexpected one on Spreeflo's side, it says the change may or may not have been applied, so check the current state with the matching get_ or list_ tool before trying again.
Working with documents
Campaigns, journeys, segments, forms, and email templates are created and updated by submitting a whole JSON document. The JSON Schema your client sees gives structure only — it doesn't tell you the node vocabulary, which operators each segment rule type allows, how form slides are ordered, or how personalisation variables are declared.
That's what read_format_doc is for. It serves those specs on demand, verbatim and never truncated:
| Slug | Covers |
|---|---|
capability-summaries | Start here — what each part of the platform can express, in one page. |
sequence-json-format | The campaign and journey node-graph wire format: node shapes, per-type config, next/branch wiring, id rules. |
automation-nodes | Every trigger, process, and action node — options, defaults, runtime behaviour such as re-enrollment and pacing, and plan gating. |
segment-json-format | The ConditionGroup / BasicRule wire format, and which fields each rule type reads. |
segment-builder | Filter categories, the operator set allowed for each data type, time windows, and AND/OR grouping. |
form-json-format | The questions array and settings: question types, slide ordering, contact mapping, theme. |
email-json-format | Builder-JSON sections, layouts and content blocks, nesting rules, and personalisation variables. |
Read them in pairs. sequence-json-format goes with automation-nodes; segment-json-format goes with segment-builder. A sequence whose nodes embed criteria — criteria match, cyclic, if/else, multi-way split, wait condition — needs all four.
The same specs are also served publicly by the Spreeflo REST API at GET /1.0/format-docs and /1.0/format-docs/{slug}.
Updates replace the whole document
These are not partial-patch APIs. An update replaces the entire document, so your client has to read the current state first and send back a complete new version. Anything it leaves out of the document is gone.
Warning: Always read before you write. If a client sends only the fields it wants to change, everything else in that document is dropped.
| Update | Read first with | What to send |
|---|---|---|
update_sequence | get_sequence | The complete new node graph. Keep the existing ids of nodes you aren't changing. DRAFT or PAUSED only. |
update_email_template | get_email_template_structure | The full sections document. Keep the id of every block you retain or modify; omit ids on new blocks. |
update_form | get_form | The full form. Keep the ids of retained questions — responses reference questions by id — and mint fresh ids only for new ones. |
update_segment | get_segment_definition | The complete new definition. Leave it out to rename the segment only. |
update_business_profile | get_business_profile | The full new business-profile object, never a partial patch. |
update_contact | — | An exception. This one is a partial edit: only the fields you pass are changed. |
update_broadcast | get_broadcast | Also partial. Only the settings you pass change; the list of link actions is replaced as a whole. A scheduled broadcast has to be unscheduled first. |
Not available over MCP
Some actions have no MCP tool at all, because they're irreversible or they send to real people. Only a person signed in to the Spreeflo app can do them:
This applies on every client, whatever its confirmation settings. The server tells a connected client about these limits when it connects, so if you ask for one of them, your AI app can tell you to do it in Spreeflo rather than trying another route.
A few in-app AI capabilities aren't exposed over MCP at all: the agent's own memory tools, its code sandbox, its agent-identity settings, and its file handling. Those are in-app chat only — see MCP vs. the in-app AI.
Plan gating
Some capabilities are gated by plan over MCP exactly as they are in the app — popup embeds and web push are Pro, sending identities need a paid plan, and certain sequence nodes and segment rule types are gated too. A gated call fails with an error saying the feature isn't on the workspace's plan. Forms are available on every plan, including Free.
Need Immediate Help? Contact our support team at support@spreeflo.com or check our other guides for more information.