MCP tools
The hosted MCP server exposes the same tools that power Spreeflo's in-app AI, minus the ones that can't safely run outside the app. There are 67 callable tools and 15 that are listed but always refused.
This page is a map, not a specification — your client reads the full schema for 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
37 read-only tools. None of these change anything in your workspace.
| Area | Tools |
|---|---|
| Workspace & audiences | get_business_profile, list_audiences |
| Campaigns & journeys | list_campaigns, list_journeys, get_campaign, get_sequence |
| 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, tags & attributes | list_contacts, get_contact, list_tags, get_tag, list_contact_attributes |
| 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 (official help-center articles), read_format_doc (document format specs — see Working with documents) |
Creating assets
13 tools. Everything they create is real and lives in your workspace — but nothing they create is live.
create_campaign_sequence, create_journey_sequencecreate_segmentcreate_email_template, create_webpush_templatecreate_form, create_form_embed, create_popup_embed (Pro only — a free trial counts) create_tag, create_contact_attributecreate_email_identity, register_domain_identity — the domain is created in a PENDING state and the tool returns the DNS records someone has to add import_contacts_csv — bulk import from CSV content, where the header row uses attribute keys and email is required Note: A campaign, journey, or form created over MCP is not live. It exists as a draft or unpublished asset, and a person starts or publishes it in the Spreeflo app.
Editing existing assets
13 tools. Each applies the moment it's called.
| Tool | What it changes |
|---|---|
sequence_update | The node graph of a campaign or journey. DRAFT or PAUSED only. |
campaign_update | Name, settings, and UTM parameters — plus targeting, for DRAFT campaigns only. |
segment_update | A segment's definition. |
email_template_update | An email template's builder document. |
webpush_template_update | A web push template. |
form_update | A form's questions and settings. |
form_embed_update | An inline form embed. |
popup_embed_update | A popup embed. Pro only. |
tag_update | Renames a tag. |
tag_contacts | Adds or removes tags on one contact by name. Unknown tags being added are created. |
contact_update | A contact. This is a partial edit — only the fields you pass change. |
email_identity_update | The display name of a sender identity. The address itself can't be changed. |
profile_update | The workspace business profile. |
If you're comparing surfaces: over MCP the write tools are named for what they do — create_form, form_update — because that's exactly what happens when they're called.
Lifecycle and duplication
campaign_pause — pauses an ACTIVE or SCHEDULED campaign or journey. Contacts already in flight hold their place and continue if it is resumed. campaign_duplicate, email_template_duplicate, webpush_template_duplicate — copies are always created as drafts. Pausing is available but starting and resuming 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:
render_chart — turns a Vega-Lite spec into a stored chart artifact and returns its URL.export_form_responses_csv — the same flattened CSV as the in-app export, capped at 10,000 rows per export.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 at GET /1.0/format-docs and /1.0/format-docs/{slug}, and through the CLI with spreeflo format-doc.
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 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 |
|---|---|---|
sequence_update | get_sequence | The complete new node graph. Keep the existing ids of nodes you aren't changing. DRAFT or PAUSED only. |
email_template_update | get_email_template_structure | The full sections document. Keep the id of every block you retain or modify; omit ids on new blocks. |
form_update | get_form | The full form. Keep the ids of retained questions — responses reference questions by id — and mint fresh ids only for new ones. |
segment_update | get_segment_definition | The complete new definition. |
profile_update | get_business_profile | The full new business-profile object, never a partial patch. |
contact_update | — | The exception. This one is a partial edit: only the fields you pass are changed. |
Not available over MCP
15 tools are listed in the catalog but always refuse. They're listed rather than hidden so a connected agent is told "a person does this in the app" — instead of inventing a workaround, like blanking every field one at a time in place of a delete.
The refusal is server-side. It applies on every client, regardless of that client's confirmation settings.
| Category | Refused tools | Why |
|---|---|---|
| Sends & publishes | campaign_start, campaign_resume, form_publish | They reach real people. A person signs in and does this in the app. |
| Deletes | campaign_delete, segment_delete, email_template_delete, webpush_template_delete, form_delete, form_embed_delete, popup_embed_delete, tag_delete, contact_delete, contact_attribute_delete, domain_identity_delete, email_identity_delete | They're irreversible. |
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 are Pro, and certain sequence nodes and segment rule types are gated too. A gated call fails with an error naming the requirement. 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.