Skip to main content

​
Start with a read

After connecting your client, ask it to list your projects and inspect one before making changes:
The connected user must have access to the project. Use the returned project ID for subsequent calls.

​
Give the client a clear scope

Name the project, branch, and requested outcome. For example:
For writes, specify the target branch and ask for a proposed change first:
Client approval settings determine when you are prompted. A prompt asking for approval does not enforce a read-only connection; Flow permissions remain the access boundary. Use a test project and working branch when trying write tools. Branch identifiers and aliases follow the API conventions.

​
Discover tools and inputs

Ask your client to list available Flow tools. Tool names begin with flow_; their input schemas describe the required arguments. Tools group request inputs into path, query, and body where the operation needs them. Use the schema returned by the server. Authentication and the workspace are supplied by the connection, not by your prompt. The endpoint reference explains the underlying operation. For common workflows, see Read entities, Batch writes, and Trigger and poll automations.

​
Limit the tools your client loads

By default, the MCP URL exposes every Flow tool. To load only the tools a workflow needs, open Settings → API & MCP, select tools under MCP URL, and copy the updated URL. Flow adds the selection as a comma-separated tools query parameter:
Replace the URL in your client configuration and refresh its tools. Flow does not store the selection; it applies to clients that use that URL. With a selection, the tool list and the flow://customer-api/openapi and flow://customer-api/tool-index resources include only the selected tools. A call to a tool outside the selection fails. Flow rejects a URL that repeats the tools parameter with 400. A selection only narrows the tools. The connected user’s permissions still apply. To restore every tool, choose All tools and copy the URL again, or remove the tools parameter.

​
Create and edit automations

MCP clients can create, update, and delete project automations. Flow saves a new automation turned off (enabled: false), and it runs only after a person turns it on in Flow. The response includes a url that links to the automation. Give that link to the person who reviews and enables it. A request that sends enabled: true is refused. To change what an enabled automation runs, or how or when it runs, turn it off first (enabled: false), make the edit, and share the url so a person can turn it back on. Otherwise Flow returns 409. Renaming an enabled automation, turning it off, or changing who is notified works without turning it off first and leaves it on.

​
Inspect reference resources

Clients that support MCP resources can read: Refresh the client’s tools after an API update. Avoid hard-coding a tool name without checking the current tool list.

​
Handle results and errors

Tool results include the API response body and HTTP status. A failed API request is reported as a tool error. Correct invalid inputs before retrying. For a permission error, check the connected user’s access. If a write times out, read the affected data before repeating it: a timeout does not prove the write failed. Long-running automations require a separate call to retrieve their result. Follow Trigger and poll automations for run identifiers and polling behavior.