Runner MCP

The Runner lets an AI assistant execute the workflows already in your account, and read back the results — without you opening AI-Flow.

Endpoint: https://mcp.ai-flow.net/runner

Requirements

• Tier 3 or above to execute a flow. Everything else works below it; runFlow returns a clear error.
• An API key, created in AI-Flow → settings → API tab.
• A flow that is API-compatible — it needs api-input and api-output nodes. See API Nodes. A flow without them can be listed, but not run.

Setup

Claude Code

Create .mcp.json in the folder you work from:

{
  "mcpServers": {
    "ai-flow-runner": {
      "type": "http",
      "url": "https://mcp.ai-flow.net/runner",
      "headers": {
        "Authorization": "Bearer ${AI_FLOW_API_KEY}"
      }
    }
  }
}

Then export your key and start the assistant:

export AI_FLOW_API_KEY=sk-af-...
claude

Because the file references an environment variable rather than the key itself, it stays safe to commit or share with your team.

Placed in a project folder, this configuration applies to that folder only.

Other clients

Any MCP client that supports Streamable HTTP with a custom header works — Cursor and others follow the same shape. Point it at the endpoint above and send Authorization: Bearer <your key>.

OAuth is not supported. The connection is authenticated by your API key alone.

What the assistant can do

Tool	Purpose	Costs credits
getAccountInfo	Current credits and tier	No
listFlows	Your flows	No
getFlowSchema	A flow's inputs and outputs	No
runFlow	Execute a flow	Yes
getRunResult	Read a run's result	No
listRuns	Recent runs	No
createUploadUrl	Get an upload link for a file input	No

You do not call these yourself — you ask in plain language, and the assistant picks the tools.

How a run works

runFlow waits for the result and returns it in a single call, so a normal run is one round-trip for the assistant.

Under the hood the run is still asynchronous: the flow is submitted, then polled every five seconds. The wait is capped — 120 seconds by default, 240 at most. If the flow is still running when that budget runs out, you get the run id and a pending status instead of an error, and the assistant picks the result up later with getRunResult. Nothing is lost, and the run is not restarted.

For a long flow you can also ask the assistant not to wait at all, and come back for the result.

Files

To send a file into a flow, the assistant asks for an upload link, uploads the file, and passes the resulting download URL as the input. Upload credentials last about ten minutes, and files are capped at 300 MB.

Results come back as links. They expire in about 12 hours, so download anything you want to keep — ask the assistant to save it locally as part of the same request.

Costs and safety

Every runFlow spends real credits from the account that owns the key, and/or uses that account's provider keys. This includes running a public or shared flow that someone else authored: the caller pays, not the author.

Practical habits:

• Ask for a run count up front rather than "keep going".
• Have the assistant check getAccountInfo before a batch.
• Create keys with an expiry rather than "never expires". A key ends up in a config file or a secrets manager; an expiring one limits the damage if it leaks.
• Revoke a key the moment you suspect it has been exposed — the API tab lists your keys and their expiry.

Limits

• Runs are rate-limited per account: 20 per minute and 300 per hour at tier 3, higher above. Exceeding it returns a clear retry delay rather than a failure.
• listFlows returns flows you own. A flow shared with you can still be run if you know its id — and it spends your credits.
• The Runner cannot create or modify a flow. That is the Builder.

Troubleshooting

The assistant does not see the server. Check that the key is exported in the same shell that started the assistant, and that the client reports the connection (in Claude Code: /mcp).

"Authentication failed". The key is wrong, revoked, or expired. Expired keys stop working immediately — check the expiry column in the API tab.

"This feature requires a higher user tier". Running through the API needs tier 3.

A flow is listed but cannot be run. It has no api-output node. Open it in the API Builder and add the API nodes.