Skip to main content

Build via MCP

Flowera ships an embedded MCP server that lets you build and manage AgentFlows programmatically — everything you can do on the canvas, driven from code or from an AI coding assistant instead of by dragging nodes.

Advanced / developer feature

This page is for developers and technical users. Building flows through the MCP means working with API keys, JSON requests, and node internals. If you're building a bot for the first time, start on the canvas and come back here once you're comfortable — everything below is optional. The visual builder and the MCP produce the exact same flows.

What it is​

MCP (Model Context Protocol) is an open standard for giving tools to AI assistants and scripts. Flowera exposes an MCP server inside the Flowera app — no separate service to run — at a single endpoint:

POST /api/v1/mcp

Through it, a client (for example an AI coding assistant, or your own script) can read the node palette, read a whole flow or a single node, and create, update, validate, run, and export flows — the same operations the AgentFlow UI performs, but callable from code. The server takes care of the fiddly parts: it turns a simple description of your nodes and connections into a complete, valid flow, and it checks the result before saving.

When you'd use it​

The canvas is the right place for most work. Reach for the MCP when you want to:

  • Generate flows from a description instead of building them by hand.
  • Create many similar flows (one per client, per region, per campaign) from a template.
  • Version or review flows as code, exporting and importing them alongside the rest of your project.
  • Let an AI assistant build and iterate on a flow for you — describe the outcome, and have it wire the nodes, pick a model, and run a test.
  • Automate repetitive edits across flows without clicking through the UI.

Authentication — a Flowera API key​

The MCP authenticates with a Flowera API key — the same keys you manage in the API Keys tab. Pass it as a Bearer token on every request:

Authorization: Bearer <your-flowera-api-key>

The workspace is derived from the key. Every operation is scoped to that one workspace, and the server blocks any access to another workspace's flows, data, or credentials.

Treat the key like an operator credential

An MCP-capable API key has the same power as someone building flows by hand in that workspace — it can create and run flows. Store it as a secret, never commit it to source control, and rotate it if it's ever exposed.

The MCP works against whichever Flowera environment your key belongs to (your local instance, or a hosted one) — the key and the URL must point at the same place.

Connecting an app instead of pasting a key​

An API key is the right tool when you are driving the MCP from a script or a coding assistant you control. When you want to connect a third-party app — Claude, ChatGPT or Codex, for example — pasting your key into it hands over everything that key can do, permanently, in whatever workspace the key belongs to.

For that case Flowera also supports connecting the app, the same way you'd connect Google or Meta. You sign in to Flowera, see exactly what the app is asking for, and approve it:

  1. The app sends you to Flowera and you sign in as normal.
  2. You choose which workspace the app may work in. It gets that one and no other.
  3. You see what it will be able to do — read your flows, build them, run them, read customer conversations, see connected accounts — each as a separate line, and you approve deliberately.
  4. Flowera shows you where the connection is being sent, so you can tell a real app from something imitating one.

An app connected this way asks for the least it needs. Reading your flows does not include reading your customers' conversations, and building a flow does not include running it at real customers — those are separate permissions the app must ask for on its own.

Some apps — ChatGPT, for example — also ask to know who you are. On the approval screen that shows as two more lines, Know it is you and See your email address. They give the app your Flowera account ID, plus the email address of your account and whether it has been verified — and nothing else: no flows, no customer data, nothing in your workspace. Apps that don't ask, such as Claude, never receive it.

Connecting ChatGPT, Codex or Claude​

Give the app your MCP address as the server URL — on Flowera cloud that is https://portal.flowera.ai/api/v1/mcp. There is no key to paste: the app sends you to Flowera to sign in and approve, as described above.

  • ChatGPT and Claude receive the connection at their own website, which the approval screen shows you.
  • Codex receives it on your own computer, so the approval screen warns you about that. That's expected — continue only if you just started the connection yourself.

For Claude step by step — including Claude Team and Enterprise plans — see Use Flowera from Claude.

Managing what's connected​

Every app you've connected appears under Connected apps in Flowera. From there you can:

  • See what each app can do and which workspace it's working in.
  • Move an app to a different workspace if you picked the wrong one.
  • Disconnect it, which takes effect immediately.
You'll only see the approval screen once

After you approve an app the first time, reconnecting it doesn't ask again — so Connected apps is where you change your mind. If you chose the wrong workspace, change it there rather than disconnecting and reconnecting.

Nothing about this replaces API keys. Existing keys, scripts and assistants keep working exactly as they do today; connecting an app is an additional option, not a migration.

What you can do with it​

The server groups its operations into a handful of areas. At a high level:

Discover the building blocks​

  • List node types and read a node's exact inputs before you configure it — so you never guess a parameter name.
  • Resolve dynamic options (available chat models, connected WhatsApp/Instagram accounts, sub-flows, tools) to the real choices in your workspace.

Read existing flows​

  • List flows in the workspace, and read a whole flow, a single node, or its connections.
  • Inspect executions, messages, and leads to see what a flow produced.

Create and edit flows​

  • Create a whole flow from a minimal description — you list the nodes and the connections between them, and the server builds the complete, canvas-compatible flow for you.
  • Make surgical edits — add, update, rename, or delete a single node; connect or disconnect two nodes — without rebuilding the rest.
  • Validate before you rely on a save, so you catch a broken connection or a missing model before the flow ever runs. Validation also flags a step that the flow's branches can never reach (for example two branches of one Condition leading to the same step), and a Wait duration that is not in HH:MM:SS form.
  • Export and import flows to move them between workspaces or store them as files.
  • Build WhatsApp and Instagram flows the right way — the assistant sets up the WhatsApp or Instagram trigger on the Start node with one of your connected accounts, and replies through the WhatsApp / Instagram tool so the message actually reaches the customer. Validation warns if a channel flow has no way to reply, or if a WhatsApp campaign could only send free text (which WhatsApp rejects outside the 24-hour window — use an approved template). The assistant can also list your WhatsApp Flows and their status — only published ones can be sent, and it can create and send WhatsApp message templates (see WhatsApp templates below). Accounts are connected in the app; the assistant cannot connect them for you.

Choose the AI model​

  • List available models — every provider and model, which ones have a ready-to-use platform key, and which of your workspace credentials apply.
  • Default model — when you don't name a model, the assistant normally builds new nodes on Azure OpenAI gpt-5.4. To use another one, just say so (for example "use Claude Sonnet"). The assistant keeps using it for the rest of that conversation. Nodes that already have a model keep it unless you ask to change it.
  • Set a node's model in one step for Agent, LLM, Condition Agent, and Human Input nodes — the server writes the provider, model, and credential correctly together (a common source of "model is required" mistakes when done by hand). See Models.

Run and debug​

  • Run a flow with a test message and get the reply back, plus a compact trace showing which nodes ran and, for branch points, which branch fired.
  • Trigger a webhook, and browse executions, messages, and leads. Executions page through a flow's whole history and can be narrowed by date, status, or session.

Build and watch automations​

Everything the Automations screens do is available here too.

  • Set up a schedule — one-time at a chosen moment, or recurring on a cron, in your own timezone.
  • Send to a list — upload a CSV or Excel file of recipients straight through the conversation, pick a file already in your workspace, or select recipients with a lead filter and see how many match before you commit. The assistant is asked to send the list's row count with it, and when it does, a list that was shortened on the way is refused instead of being sent short. A file too big to carry through the conversation should be uploaded in Flowera (Assets, or the automation wizard); the assistant then picks it from your workspace.
  • Check it before it goes live and run it on demand — see below for the two safeguards that apply.
  • Watch a run — how many recipients succeeded, failed or are still going, and the most common errors. It can wait for a batch to finish instead of you asking repeatedly.
  • Put things right — retry the recipients that failed, release a held canary, export the results as a file, and work through the failure queue.
Two safeguards you will notice

A new automation is saved paused. Creating one never puts it live; an assistant has to activate it as a separate step, and activation refuses if something would make it misfire — a start time already in the past, a recipient file that has been deleted, a filter matching nobody. You get the list of what to fix.

Running a batch immediately asks first. The assistant's first attempt sends nothing: it comes back with how many people would be contacted and where that number came from. Only after you say yes does it actually run. This is deliberate — a batch can reach tens of thousands of customers and cannot be recalled.

Manage files and send them on a channel​

The workspace's file library is available too, which is what makes "here's a product photo — send it to customers on WhatsApp" something an assistant can do start to finish.

  • See what's there — list the workspace's files, filter by type or by whether they're published, search by name, or look at just one document store's files.
  • Add a file — send it through the conversation (up to roughly 1.4 MB), or give a public link and Flowera downloads it. Either way Flowera checks the file really is what it claims to be, so a link that has quietly expired and now returns a login page is refused rather than stored as your product photo.
  • Tidy it up — category, tags, description and image alt text.
  • Publish or unpublish — and this is the one that matters for sending.
A file has to be published before a flow can send it

{{ $assets.<name>.url }} only produces a working link while the file is public — that is what lets the WhatsApp, Instagram and Facebook send-media steps deliver it. Ask for a file to be published and the assistant will tell you, every time, what publishing means: anyone with the link can download it, with no login. Don't publish anything with customer or personal data in it.

Unpublishing changes the link so Flowera stops serving the old one immediately — but it can't reach copies already downloaded or cached, which can survive for up to a year. Treat a file that was ever public as public for good.

If a flow points at a file that is still private, the assistant will say so when it saves or checks the flow, rather than leaving you to find out from a customer who got a message with no picture in it.

What the MCP can't do

It cannot create credentials or connect a new WhatsApp/Instagram account — those are one-time manual steps in the UI. The MCP can only pick from accounts and credentials that already exist in your workspace.

It also cannot delete a flow or a file. Deleting a flow deletes every automation attached to it, and deleting a file breaks every flow and document store using it — so both stay deliberate actions you take in the app where you can see what goes with them.

Very large recipient files can't travel through a conversation — above roughly 1.4 MB the assistant will ask you to upload the file under Assets in the app, and can then pick it up from there.

Manage WhatsApp templates​

Everything the WhatsApp templates dialog does is available here too — and two things it can't do: edit templates the editor can't display (named variables, coupon-code buttons, media carousels), and put an approved template into a flow with every value filled in.

ToolWhat it does
list_whatsapp_templatesLists templates in every status, with the rejection reason and quality, filtered by status, category, language or name. For each one it says whether it can be sent and which values a send needs. Without an account it lists every connected WhatsApp number, with how many templates each has out of its limit.
get_whatsapp_templateOne template in full — its content, whether it can be edited, and which flows and automations send it.
upload_whatsapp_template_mediaUploads the sample image (JPEG/PNG up to 5 MB), video (MP4 up to 16 MB) or document (PDF up to 100 MB) Meta needs to review a media header — from a workspace file, a public link, or the conversation itself (up to roughly 1.4 MB).
create_whatsapp_templateCreates a template from the editor's fields, from a preset (order_confirmation, shipping_update, appointment_reminder, otp_code, promotion, product_carousel, blank) with your changes, or from Meta's raw format for features the editor doesn't have.
update_whatsapp_templateEdits a template and sends it back to Meta review.
delete_whatsapp_templateDeletes one language of a template — or every language, if asked explicitly.
set_node_whatsapp_templatePuts a template into a Tool node or an Agent's WhatsApp tool and fills its variables, header media, catalog products and button values. Values can be flow variables such as {{$flow.state.name}}.
Nothing reaches Meta until you say yes

Creating, editing and deleting all take two steps. The first call sends nothing: it checks the template against the editor's and Meta's rules, shows a text preview of the message, and — for an edit or a delete — lists the flows that send the template and what would break in them. The assistant shows you this and only goes ahead after you agree.

  • Delete removes one language unless you ask for all of them, and refuses while a flow still sends the template unless you insist. Deleting an approved template blocks its name for 30 days.
  • Editing an approved template takes it offline until Meta approves it again, and Meta allows it once every 24 hours.

A few more things the assistant handles for you:

  • The sample is not the send. A header uploaded for review is never what customers receive. When the template is put into a flow, the header needs a public link — for example a published file.
  • Template sends are checked. Every save flags a template send with an empty variable, missing header media, or broken raw JSON. When the assistant validates, runs, or wires a flow, it also checks with Meta that the template still exists, is approved, and hasn't been edited since it was put into the flow.
  • A template sent again on every reply is flagged. If a flow both answers WhatsApp messages and sends a template from a Tool node that every run reaches from Start, each customer reply sends the template again. Validation warns about this. The fix is a Condition on {{ $flow.triggerType }} in front of the send: schedule or batch-row is the automation's own run, webhookInput is a customer reply.
  • Nothing overrides the template it puts in. set_node_whatsapp_template removes older settings that would replace the template at run time — a legacy tool selection left on the node, and templateName / languageCode / components pinned as tool arguments — and lists what it removed in cleaned.
  • Verification code templates need only the code. Give variable "1"; the copy-code button is filled with the same code automatically.

Example — "send our order confirmation in Turkish to new customers." The assistant works through these calls; you approve the template before it is submitted:

1. list_whatsapp_templates        → finds the WhatsApp number (credentialId) and the existing templates
2. create_whatsapp_template       → preset "order_confirmation", name "siparis_onay", language "tr",
                                     Turkish body with examples; returns a preview, sends nothing
3. create_whatsapp_template       → the same call with confirm: true; status PENDING
4. get_whatsapp_template          → checked again later, until the status is APPROVED
5. set_node_whatsapp_template     → the flow's WhatsApp Tool node, variables
                                     {"1": "{{$flow.state.name}}", "2": "{{$flow.state.orderId}}", "3": "{{$flow.state.deliveryDate}}"}
6. validate_agentflow             → runnable: true — the template is live, approved and fully filled in

Step 2, as the assistant sends it:

{
  "credentialId": "<your WhatsApp account id>",
  "preset": "order_confirmation",
  "template": {
    "name": "siparis_onay",
    "language": "tr",
    "body": {
      "text": "Merhaba {{1}}, {{2}} numaralı siparişiniz onaylandı. Tahmini teslimat: {{3}}.",
      "examples": { "1": "Ayşe", "2": "SP-1024", "3": "12 Ekim" }
    },
    "buttons": [{ "type": "URL", "text": "Siparişi takip et", "url": "https://shop.example.com/orders" }]
  }
}

Read and restore versions​

Every save of a flow — from the canvas, from the MCP, or from an import — is kept. Nothing is overwritten, and nothing is deleted.

  • Read the history of a flow: each version's number, where the change came from, who made it, and the note they left — optionally with a per-version summary of what changed (nodes added, removed, changed or merely moved; connections; name and settings), and filtered to named versions only.
  • Read one past version exactly as it was stored — its graph, and its settings on request.
  • Compare two versions and see what changed: which nodes were added, removed, or edited (and which of their inputs differ), and which connections came and went.
  • Restore an earlier version — its content becomes the flow's current state, recorded as a new version. Restoring v3 while you're on v7 gives you a v8 that matches v3, with v7 still there to go back to.
  • Name a version after the fact — set, replace or clear the note on an existing version, the same "Name this version" you have in the canvas's version history. Only the note changes; the version's content and the flow stay as they are.

Every operation that changes a flow accepts an optional note describing why, and reports the resulting version number. If that number doesn't go up, the change was identical to what was already saved and nothing was recorded — which is the quickest way to tell a real edit from a no-op.

Each execution also records the version it ran, so "which graph did this run actually execute" has an answer even after you've edited the flow ten times since.

A restore replaces the settings too

An earlier version holds the flow's embed and API settings as well as its graph, so restoring it can change things like the flow's rate limit. The response tells you when those differ from what's live.

The same rules still apply​

Flows built through the MCP obey the same behavior as flows built on the canvas — including the footguns. In particular:

  • Condition Agent still has no automatic Else — add an explicit catch-all scenario.
  • Runtime values in {{ }} are still $-prefixed ({{$question}}, {{$flow.state.name}}).
  • State keys name / email / phone still sync to Lead columns.

A flow that saved is not necessarily runnable — the server reports whether it can run and lists anything blocking it (for example, a node without a model). Fix the blockers before running.