Use Claude Code with FlowRunner

Claude Code is where you work. FlowRunner is where the automation runs once it’s built: on its triggers and schedule, with approvals that wait for people, and a record your team can open. FlowRunner Prompt to Flow connects the two, so Claude Code builds and changes flows in your FlowRunner workspace from a prompt.

This page walks through it: two commands to connect, one prompt that builds an approval flow, what Claude Code asks and reports back, and the code that calls the flow. Then three more ways to use them together. Samples read the workspace id and key from FLOWRUNNER_WORKSPACE_ID and FLOWRUNNER_KEY; both are in Workspace Settings, under Credentials.

1. Connect FlowRunner Prompt to Flow

FlowRunner Prompt to Flow is an MCP server you add to the AI tool you already use. You connect it once and sign in with your FlowRunner account. The server URL is the same for every tool: https://app.flowrunner.ai/mcp.

• Claude (web and desktop): open Settings > Connectors, click + Add, then Add custom connector. Enter FlowRunner and the server URL, click Add, then Connect, and approve the FlowRunner sign-in. On a Team or Enterprise plan, an Owner adds it once under Organization settings > Connectors.
• Claude Code: run these two commands in your project folder, and approve the sign-in page that opens:

claude mcp add --transport http flowrunner https://app.flowrunner.ai/mcp
claude mcp login flowrunner

• ChatGPT (on the web): open ChatGPT Plugins, click Add, then Add custom MCP server. Enter FlowRunner, put the server URL under Connection, choose OAuth, and approve the sign-in. In a chat, type @ and pick FlowRunner.
• Codex: add the server to ~/.codex/config.toml, then run codex mcp login flowrunner:

[mcp_servers.flowrunner]
url = "https://app.flowrunner.ai/mcp"

• Cursor: add the server to ~/.cursor/mcp.json, then open Customize > MCPs and follow the sign-in prompt:

{
  "mcpServers": {
    "flowrunner": { "url": "https://app.flowrunner.ai/mcp" }
  }
}

If you don't have a FlowRunner account yet, the Free plan needs no card, and every new account starts with 14 days of Professional. The setup guide in the docs has each tool step by step.

For Claude Code, add --scope user to the first command to use FlowRunner in every project, not just this folder. Check the connection:

claude mcp list

flowrunner: https://app.flowrunner.ai/mcp (HTTP) - ✔ Connected

Inside a session, if Claude Code shows “1 MCP server needs authentication · run /mcp”, type /mcp, pick flowrunner, then Authenticate.

2. Build an approval flow from one prompt

Describe the flow the way you’d brief a colleague who can’t ask you questions: what starts it, what it does, who approves, what happens when a step fails, and what to tell you at the end. This prompt builds a refund approval that your support app calls:

Using the FlowRunner tools, build a flow called “Refund Approval”. My support app calls it through the API without waiting for an answer. It sends requestId, orderId, amount, customerEmail, and reason. Post the request to #refunds in Slack with Approve and Reject buttons and a box for a note. Wait for the answer, however long it takes. Then POST JSON to https://support.example.com/hooks/refund-decision with requestId, approved (true or false), note, and who answered. Send the header X-Approval-Secret on that request, and leave its value empty: I’ll paste it into the HTTP Request block myself in the flow editor. Retry that call on 429 and 5XX up to 3 times with exponential backoff, and if it still fails, post the error and the request id in #refunds. Ask me before you make it live, and tell me exactly what my app sends and what my endpoint receives.

Claude Code reads the server’s instructions, finds your workspace, builds the flow, and checks it. In the default permission mode it asks before each FlowRunner action. Below is a sample session, reconstructed and trimmed to show its shape. It isn’t a recording, and your names, ids, and wording will differ:

⏺ flowrunner - Create Flow (MCP)

  Do you want to proceed?
  ❯ 1. Yes
    2. Yes, and don't ask again for flowrunner - Create Flow commands in /Users/you/support-app
    3. No

⏺ Built "Refund Approval" in your workspace. It's not live yet.

  What starts it: your app calls the flow through the API without waiting.
  The call returns only an executionId; the decision comes later, to your endpoint.

  Your app sends:
    {"requestId": "r_1042", "orderId": "1042", "amount": 180.0,
     "customerEmail": "[email protected]", "reason": "Arrived damaged"}

  Your endpoint receives (POST https://support.example.com/hooks/refund-decision):
    {"requestId": "r_1042", "approved": true, "note": "", "approvedBy": "Sam Lee"}
    with the header X-Approval-Secret.

  Blocks:
    - Post Refund Request (Slack): posts to #refunds with Approve, Reject, and a note box
    - Wait for Decision: holds the run until someone clicks a button
    - Send Decision (HTTP Request): retries on 429 and 5XX, 3 attempts, exponential backoff
    - Handle Error -> Post Failure (Slack): posts the error and the request id to #refunds

  Before it can run:
    1. Connect Slack. Open this link and sign in (it works once, for 30 minutes): <link>
    2. Set the secret. Send Decision has an X-Approval-Secret header with an empty
       value. Paste your secret into it in the flow editor.
    3. I can't see the address your app calls. In the flow editor, open
       Launch Flow Instance > cURL. Flow id: <flow-id>

  I haven't started a test run: it would post a real message in #refunds and wait for a click.
  Want me to make the flow live? Going live also turns on its Slack trigger.

> Slack is connected and the secret is set. Make it live.

⏺ flowrunner - Start Flow (MCP)

⏺ Refund Approval is live.

A few things to know about what happened:

• The flow is yours, on the canvas. It’s in the workspace’s flow list. Open it in the flow editor to check the blocks, or ask Claude Code to change it. Read what the AI says it built.
• It asked before going live, and it didn’t run anything that would reach a real person. A live flow’s triggers and schedule turn on with it.
• It can’t do everything. It can’t create a FlowRunner Form or attach a flow to an AI agent as its tool yet, and it says so when your prompt needs one; you add those in the flow editor. It can’t delete a flow.

If the first build isn’t what you meant, describe the change in a new prompt and Claude Code changes the same flow.

3. Call the flow from your code

Your app starts the flow with the non-blocking Call Flow API, using the flow id from Claude Code’s answer and the key in a header:

import os
import uuid
import requests

FR_ACTIVATE = (
    "https://api.flowrunner.ai/api/v1/"
    f"{os.environ['FLOWRUNNER_WORKSPACE_ID']}/flows/<flow-id>/activate"
)


def request_refund_approval(order_id: str, amount: float, email: str, reason: str) -> str:
    request_id = f"r_{uuid.uuid4().hex[:12]}"
    pending_refunds.save(request_id, order_id, amount)  # your database
    r = requests.post(
        FR_ACTIVATE,
        headers={"FR-Access-Key": os.environ["FLOWRUNNER_KEY"]},
        json={
            "requestId": request_id,
            "orderId": order_id,
            "amount": amount,
            "customerEmail": email,
            "reason": reason,
        },
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["executionId"]

When someone clicks Approve or Reject, the flow POSTs the decision to your endpoint. Check X-Approval-Secret, look up the request id, act on it once, and answer with a 2xx. The run can wait up to 30 days on Free, Starter, and Growth, and up to a year on Professional and above, and the whole run counts as one execution. Its record, with the request, the answer, and who gave it, is on the flow’s Instances tab.

Keep the key server-side. Claude Code can read the workspace key through FlowRunner Prompt to Flow, and a tool that can run commands can use it to start runs, so keep it asking before it starts a run, runs a single block, makes a flow live, or stops one.

4. Check runs and change a live flow

Claude Code can read the flow’s run history, after asking you, and explain a failure:

Two runs of Refund Approval failed yesterday. What happened?

It tells you which step failed, why, and whether the cause is in the flow or outside it, such as a Slack account that needs signing in again or an endpoint that refused the call. Ask it to fix the flow and it does.

A live version can’t be edited, so Claude Code stops the flow, changes it, and makes it live again, and calls fail in between. For a flow your app depends on, click Clone in the flow editor’s toolbar first, then ask Claude Code to change the copy and not make it live. When the copy is ready, click Start flow on it and choose SUSPEND & ACTIVATE to swap it in.

Pattern: Claude Code writes your custom block

When a flow needs your own API, a private system, or an npm package, a custom extension turns it into blocks in the palette. The FlowRunner CLI installs Claude Code agents that write it:

npx @flowrunner/cli@latest init -d my-extensions
cd my-extensions
npx flowrunner login
npx flowrunner init-claude

login opens a browser page where you pick the workspace to deploy to. init-claude adds two agents to .claude/agents, flowrunner-service-code-engineer and flowrunner-service-test-engineer, and a FlowRunner block to CLAUDE.md. Open Claude Code in the project and describe the service in a sentence:

I need a service for our internal inventory API with a Get Stock Level action that takes a SKU and a Reserve Stock action that takes a SKU and a quantity. The base URL and API key are workspace settings.

Claude Code writes the service and its tests and runs them. Then deploy:

npx flowrunner deploy

The extension is one JavaScript module, and its node_modules ship with the deploy (up to 50 MB). The deploy prints a link to the extension’s settings, where you enter the base URL and key. Its actions then appear in the block palette under Custom Extensions, so Claude Code (through FlowRunner Prompt to Flow) and your teammates (in the editor) can use them in any flow in the workspace. The AI quick start in the docs has the full walk-through.

Pattern: a hook tells your team through FlowRunner

A Claude Code http hook POSTs the event’s JSON to a URL. Point it at a FlowRunner flow and the flow can post to your team’s Slack channel when a long session finishes or stops at a permission prompt. Build the flow with a prompt (“when called, post the message and the working directory to #dev-agents”), then add the hook to .claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.flowrunner.ai/api/v1/<workspace-id>/flows/<flow-id>/activate",
            "headers": { "FR-Access-Key": "$FLOWRUNNER_KEY" },
            "allowedEnvVars": ["FLOWRUNNER_KEY"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Claude Code sends the event as JSON, and each top-level property becomes part of the run’s Initial Data. Only variables listed in allowedEnvVars are filled into headers, so the key stays in your environment. Each call is one execution, so choose the events that matter.

Pattern: a business event starts Claude Code

Claude Code’s cloud scheduled tasks can start from an HTTP POST to the task’s own endpoint with a bearer token. A FlowRunner flow can make that call when something happens in a business app: a bug report arrives through a form, an issue is labeled in your tracker, a customer reports an error by email. Put the call in an HTTP Request block with a Retry Policy, and the run record shows what started the task and what it was sent. Leave the bearer token out of the prompt you paste, and type it into the HTTP Request block’s header yourself in the flow editor.

Optional: turn a script or agent into a flow

Claude Code can read code in your repo, and with FlowRunner Prompt to Flow connected it can build a flow that does the same job: a cron script that copies orders into a sheet, or agent code that classifies tickets. FlowRunner Prompt to Flow has done this with the Agents SDK code OpenAI Agent Builder exports (six real conversions). Ask Claude Code to read the file, keep the same behavior, and list anything it can’t map one to one before it builds.

That’s an option for code the rest of the team needs to read and change on a canvas. Code that belongs to your product stays in your repo, and FlowRunner calls it or is called by it.