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, 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.

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.
  • Export and import flows to move them between workspaces or store them as files.

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.
  • 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.
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.

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.