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.

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