Connect Your Apps

How do I make Support helper use the right app account? Create a connection through Controller AI’s credential form or provider authorization. Confirm the account, then bind its ID to the intended node or action. Enter secrets in the secure form, never in assistant chat. A link or card is not a completed connection.

Find and authorize the exact app

In the app: open Connections, then Add connection on an empty page or Add Connection in the header when accounts exist. Search for the app and complete its form or provider authorization.

With an assistant: for a new action, discover its exact integration/action pair below, authorize it, then follow Add agent tools to attach it. For workflow repair, find the node first. To replace an agent action’s account, find your owned agent. Substitute your agent’s name if you did not build Support helper.

cai agent list --search "Support helper" --ownership mine --json

Select one exact displayed-name match and note its data.agents[].id as <agentId>. Search matches substrings, so if names are duplicated, have the owner choose the ID.

Now list its tools:

cai agent tools <agentId> --json

MCP uses agent_tool_list with agentId. Note the intended action’s data.tools[].id as <toolId> and nodeSlug as <nodeSlug>. Use that exact integration for the replacement.

For first-time setup, search for the action:

cai integration actions "Send a Slack message" --json

MCP uses integration_action_list with query: "Send a Slack message". Select the intended data.items[] action, keeping its exact nodeSlug as <nodeSlug> and key for attachment. Display names alone do not identify the integration.

Now list that integration’s accounts:

cai connection list --integration <nodeSlug> --json

Reuse the intended ACTIVE account if listed. Only when none is suitable, authorize another:

cai connection connect <nodeSlug> --wait --json

The CLI requests a browser opening and waits up to 300 seconds by default. If no browser appears, open the printed URL. For a remote handoff, print the link instead:

cai connection connect <nodeSlug> --no-open --json

MCP uses connection_connect_url with nodeSlug, returning url in its result data without waiting. Share the CLI’s data.url. Links are single-use and expire after 30 minutes. After a timeout, list again before authorizing again, and reuse the link only while it is unused and unexpired.

An assistant in Controller AI’s hosted builder uses a card request:

cai connection request <nodeSlug> --json

data.requestedInChat: true confirms card delivery. An existing active connection returns connected: true without a card. If you get cardDeliveryFailed: true, retry once, then share connectUrl. This command has no public MCP tool.

Confirm the account and bind it

List the accounts again:

cai connection list --integration <nodeSlug> --json

Compare the IDs before and after. Use data.connectionId from a successful --wait, or the intended data.items[].id, as <connectionId>. Display names in the CLI and MCP do not prove provider identity. Have the user confirm their selection, and inspect Linked account in Connections when present. The list excludes system connections.

Statuses are ACTIVE, MISSING, and ERROR. ACTIVE is stored eligibility, not a provider health check. Bind an ACTIVE connection with the exact slug. CLI and MCP can save an inactive connection on an action, but runtime rejects it.

In the app: open Agents → Support helper → Edit → Tools. Hover the action and choose the pencil (Edit). Select Connection → Continue → Save changes, then the agent page’s Save changes. The dialog only stages your edit.

Rebinding an action already in the published version redirects subsequent Live calls immediately, without publication. Draft-only actions have no Live callers. Shared users use the agent owner’s connection.

With an assistant, rebind the tool:

cai agent update-tool <agentId> --tool <toolId> --connection <connectionId> --json
cai agent tools <agentId> --json

MCP uses agent_tool_update with agentId, toolId, and connectionId as strings. Verify the tool’s saved connectionId. Test against a designated Slack test channel, because tests perform real provider actions. Successful calls and provider-reported failures are billable, so inspect provider state before retrying an uncertain write.

Repair a workflow node’s account

In the app: an active workflow opens read-only in Live, so switch to Dev first. Open Workflows → Support desk → Dev → intended flow → intended action node → Connection and select the replacement account.

With an assistant: these examples assume no pinned workflow and pass --workflow explicitly. Start by listing workflows.

cai workflow list --json

Note the intended data.items[].id as <workflowId>. Then list that workflow’s flows.

cai flow list --workflow <workflowId> --json

Note the intended data.items[].id as <flowId>. Then read the flow to get its nodes.

cai flow get <flowId> --workflow <workflowId> --json

Note the intended data.nodes[].id as <nodeId> and its nodeSlug as <nodeSlug>. If the node needs another account, complete authorization above using that slug, then resume with the confirmed <connectionId>.

Set the connection and read it back:

cai node set-connection <nodeId> --connection <connectionId> --workflow <workflowId> --json
cai node get <nodeId> --workflow <workflowId> --json
cai node props <nodeId> --workflow <workflowId> --json

MCP uses node_connection_set with workflowId, nodeId, and connection. Property readback is node_prop_list. Rebinding resets fields whose choices come from the app, such as channels or folders, and clears the dynamic field catalog. Reload, reselect destinations, and inspect all fields, because the available field set can change.

This changes development. Configure and verify the node, test its affected path, then publish the workflow to replace its Live binding.

Name accounts and choose a default

In the app: hover the connection card, choose the pencil (Edit connection name), and press Enter to save. Grouped accounts offer Set as default.

With an assistant, rename and set default:

cai connection update <connectionId> --name "Support workspace" --default --json
cai connection list --integration <nodeSlug> --json

MCP uses connection_update with connectionId, displayName, and isDefault: true. Check the saved name and default. The first connection becomes the default. The app preselects defaults for new compatible nodes, triggers, and actions. Setting one clears the others for that integration. Existing bindings never retarget, and deleting the default promotes no replacement.

Inspect dependents before deleting

Check dependencies in development and Live, then replace and verify bindings, publishing repaired workflows first. The map includes workflow and direct-action connection IDs, but omits Chat in Slack, so inspect those settings separately.

Deletion removes Controller AI authorization immediately, Live included, leaving stale IDs in nodes and tools. It does not revoke provider-side access. Revoke that separately when intended. Deleting a native Slack connection closes open approval episodes and attempts to post “Approval closed — Slack was disconnected.”

In the app: hover the connection card, choose the trash icon (Delete connection), then confirm Delete.

With an assistant, delete and verify:

cai connection delete <connectionId> --yes --json
cai connection list --integration <nodeSlug> --json

MCP uses connection_delete with connectionId, without a yes parameter. Confirm the ID is absent and inspect affected callers.