Build a Workflow with Builder MCP v2

Builder MCP lets an AI agent discover Flowgear contracts, create a Workflow, run it in Debug mode, diagnose failures, and save the tested result. This guide applies after you have registered the Builder MCP Server in a compatible client.

Use a Test Environment for this process. Builder MCP creates and changes persisted Workflows and requires Site Administrator access.

Before you build

Check that the MCP server is registered and authenticated. Copy the instructions in the MCP option from the main navigation in the Console to configure it for the first time. If you are working across multiple tenants, ensure that each MCP server you are registering has a unique name and ensure that your agent knows which one to use for your current workspace. This is most easily done by specifying the name of the MCP Server that should be used in your AGENT.md file in your project folder.

Once connected, the agent should be directed to obtain the builder resource via the instructions sent to it. If you need to troubleshoot, ask the agent to complete these checks at the start of the session:

  1. Load the flowgear://builder/guidance Resource once. If the client cannot read MCP Resources and the guidance is not already present, call GetBuilderGuidance once instead.
  2. Call GetBuilderContext and show you the connected Tenant, Site, and Environment.
  3. Stop if the target is not the Test Environment you intend to change.

Builder MCP does not have access to an open Console canvas. For a new Workflow, specify a Folder or Cluster only when you need one. Otherwise, the agent creates it in the root folder for the default cloud runtime.

Describe the result

Give the agent an outcome and the constraints it must preserve. Include:

  • The systems involved and which existing Connections it may use.
  • The Workflow inputs and expected outputs.
  • Whether the Workflow will be called by HTTP, MCP, another Workflow, or a trigger.
  • A representative payload or field contract when one exists.
  • The expected Folder and Cluster, if they differ from the defaults.
  • Any operation that can change or delete external data.

For example:

Build a Workflow named Get customer summary in the Integrations folder.
It must receive a customer ID over HTTP, retrieve that customer through an existing CRM Connection, and return only the ID, name, and account status.
Use the Test Environment. Discover the exact contracts, build the smallest runnable version, debug it, repair failures, and save only the tested result. Ask me to choose if more than one compatible Connection exists.

Do not paste credentials into the prompt. The agent can discover compatible Connection identifiers, but Builder MCP does not expose their protected values.

Follow the verified build loop

A reliable Builder MCP session follows this order.

1. Discover exact contracts

The agent should find the installed Node version, Method, template, Parameters, Returns, Connection requirements, and any input schema before writing the Workflow. Tool output is authoritative; examples are only structural guidance.

If a choice is ambiguous, ask the agent to show the discovered options instead of inventing a Node version, Connection key, Folder key, Cluster key, or schema field.

2. Build the smallest runnable slice

Start with one complete path through the Workflow. Map runtime data on the consuming Property, and avoid adding a Step only to rename or reshape fields.

For an HTTP or MCP Workflow, the receive and response Steps must form a matching pair. The response Step remains at the root level, and the transport response replaces ordinary Workflow Returns.

3. Save a blank Workflow shell

For a new Workflow, the agent first saves a blank shell with the intended name and location. This provides a persisted Workflow key so subsequent Debug runs and logs remain attached to the same Workflow identity.

The agent then keeps the Key and FileHash returned by SaveWorkflow. These values must come from Flowgear and must not be invented.

4. Debug the current YAML

The agent calls DebugWorkflow with both the persisted Workflow key and the current YAML. This tests the proposed design without requiring the final YAML to be saved first and returns an InstanceKey, materialized Workflow Returns, and auditable logs.

Testing should use small, deterministic input. Review any call that changes an external system before allowing it to run.

5. Repair the latest failure

The agent inspects the most recent gating error or failed Step, changes only the affected part of the design, and runs Debug again. Repeat until the Workflow completes successfully or the agent reports a concrete blocker that needs your input.

6. Save the tested Workflow

After a successful run, the agent calls SaveWorkflow with the tested YAML, the Workflow Key, and the latest FileHash.

The file hash prevents an update from silently overwriting a newer revision. If it is stale, the agent must call GetWorkflow, reapply the intended change to the returned definition, and retry with the new hash.

Ask the agent to report:

  • The saved Workflow name and Console link.
  • The Environment and Folder used.
  • The last successful Debug instance.
  • Any untested path, external side effect, or remaining constraint.

Verify the result in the Console

Open the link returned by the agent and confirm:

  1. The Workflow is in the intended Folder and uses the intended Cluster.
  2. The YAML contains the exact discovered Node versions and Methods.
  3. Logs shows the successful Debug run.
  4. The saved revision contains the same design that was tested.
  5. The Workflow's status and release state are appropriate for the target Environment.

Saving, enabling, and releasing are separate lifecycle actions. Do not promote the Workflow beyond the Test Environment until its trigger, mappings, failure paths, and external effects have been reviewed.

Update an existing Workflow safely

For an existing Workflow, ask the agent to call GetWorkflow before editing. It must preserve the returned Key, base the change on the current YAML, and use the returned FileHash when saving.

Keep the change focused, Debug the revised YAML under the existing Workflow key, and save only after the test succeeds. If another author updates the Workflow first, refetch it and reconcile the intended change instead of forcing the stale version through.

For setup and client-specific registration, see Builder MCP Server. For the in-Console experience, see AI Workflow assistant.