Connect an AI agent with MCP

TaskJuice ships a managed MCP (Model Context Protocol) server. Add it to Claude, ChatGPT, or any MCP-capable agent, and the agent can run your published workflows, check on runs, and — when you allow it — build new workflows, publish them, and turn them on, handing you only the steps that need a person.

Every connection is scoped. A workspace URL only ever exposes that workspace's workflows, so an agent you set up for one client can never see another client's work.

Get your connection URL

1. Open the Assistants page

   Go to AI → Assistants and open the Connect tab. You need an account admin or owner role. The scope picker at the top switches between Whole account and each workspace, and the tab shows the URL for the scope you pick. The AI agents card in Workspace settings → General links there too.

2. Copy the URL for the scope you want

   Use the workspace URL unless you have a reason not to — it is the tightest scope and the right default for client work. To build for several clients from one connection, use the whole-account URL instead (see One connection for every client):

   https://mcp.taskjuice.ai/mcp/acme-marketing/lead-gen

   Copy code

   The whole-account URL (https://mcp.taskjuice.ai/mcp/acme-marketing) exposes workflows across all workspaces your signed-in user can access.

3. Add the server in your agent

   In Claude, ChatGPT, or another MCP client, add a new MCP server (also called a connector) and paste the URL. The agent opens a TaskJuice sign-in in your browser. Sign in with your normal TaskJuice account, then on the Authorize access screen choose what the assistant may do (see Choose what a connection can do) and select Continue.

   There is no token to copy for this flow. Access follows your TaskJuice user: what you can see in the app is what the agent can see, narrowed to the URL's scope and to the permissions you ticked.

4. Confirm the tools appear

   Ask the agent to list its TaskJuice tools. You should see whoami, find, and describe at minimum; run_workflow and control_run if the connection has the Run permission (control_run is not offered to a client's own sign-in); get_skill if at least one managed skill is licensed to the connection's workspace or account; and, for a sign-in connection made by someone with an account role on a plan with authoring, the authoring tools its permissions allow, on either URL (three need only Read, the draft tools, the step test test_step, the table tools edit_table and table_rows, and delete_workflow need Build, and publish and set_workflow_state need Admin). An API key with Read and Run, with a skill licensed, sees 6 tools; a sign-in connection that meets every one of those conditions and holds every permission sees 17. Ask it to call whoami to see exactly what it is connected as. No workflow appears as its own tool: the agent finds your exposed workflows with find and runs one with run_workflow.

Choose what a connection can do

Every connection carries a set of permissions. They only ever narrow what the connection can do: your plan, your role, and the connection URL still apply, and ticking a permission never grants something they don't already allow.

Three things to know before you choose:

• Read still shows a lot. A run includes its input and output, which can hold data from your connected apps. On a plan with authoring, a sign-in connection made by someone with an account role can also read drafts and every workflow's status and runs, not only the exposed ones. On the whole-account URL that covers every workspace: drafts, deployment status, and the runs of any one workflow (find with workflowId, or a run by its id). A run list with no workflow filter still shows only exposed workflows' runs.
• Build can act in your connected apps. Testing a step (test_step) runs that one step for real, the same as the Test button in the editor: an email step sends the email and an HTTP step makes the request, with the workspace's connections. This needs Build only, not Run, so leave Build unticked for an assistant that must not send or change anything.
• Build changes some things straight away. Tables have no draft, so a table or row change an assistant makes is live as soon as it saves; deleting rows or removing columns takes the confirm step first. Saving a draft that changes which form a live form-triggered workflow listens to also takes effect straight away, the same as in the editor. Deleting a workflow is permanent: it takes the confirm step first, and only a workflow that is turned off can be deleted.

The Published tools tab in AI → Assistants shows which permission each tool needs.

Where you choose them:

• Sign-in connections — on the Authorize access screen, when you add the connector. Read, Run, and Build start ticked; Admin is never ticked for you, so a new connection can only publish if you tick it on purpose.
• API keys — in the Create API key dialog. Read is always on and Run starts ticked. A key can hold Read and Run only; Build and Admin need a sign-in connection.

To change what a connection can do, replace it. For a sign-in connection, remove the connector in the assistant and add it again: the Authorize access screen shows the choices each time. An API key's permissions are fixed when it is created, so create a new key with the permissions you want and revoke the old one.

Connections made before permissions existed keep what they could already do: API keys keep Read and Run, and sign-in connections keep all four, Admin included. To narrow an older sign-in connection, remove it from the assistant and add it again. The API keys table marks older keys "(created before permissions)". A sign-in connection's permissions show only through whoami, which reports an older connection as a legacy default.

Expose a workflow to AI agents

Agents can't find or run a workflow until you expose it. Exposing makes it findable with find and runnable with run_workflow. Each one is an explicit opt-in, made from the workflow editor. You need a workspace admin role, and the workflow must be published — agents can only run its active version.

1. Open the workflow and choose “Expose to AI agents…”

   In the editor, open the ⋯ menu in the header and select Expose to AI agents…. If the item is grayed out, the tooltip says why — usually the workflow has not been published yet.

2. Turn on the switch and write a description

   Flip Expose this workflow on, then write the description for agents — that text is what the agent reads in find and describe when choosing a workflow for a task, so describe what the workflow does and what input it expects. Leave it blank and agents see the workflow's own description (if it has one), shown in the field.

3. Check the slug and input

   The dialog shows the Slug agents pass to run_workflow — a name derived from the workflow's title. If another exposed workflow shares the title, both slugs get a distinguishing suffix, so exposing or hiding one can change the other's slug. The Input line shows what the workflow accepts, derived automatically with no extra setup: a form-triggered workflow exposes its exact published form fields; a webhook-triggered workflow exposes the fields its nodes actually read (reference $trigger.email anywhere and agents see an email field, described with the node that uses it); app triggers expose their declared payload shape. describe also returns a ready-made example input for every exposed workflow, so agents send correctly shaped input on the first call. Only a workflow whose input can't be derived — say, a manual trigger whose nodes read no trigger fields — accepts any JSON object.

Once a workflow is exposed, a small robot icon appears in the editor header — click it any time to reopen the dialog.

Two things follow from the slug tracking the workflow title, and they are worth knowing before you rely on a slug:

• Renaming the workflow changes its slug. Any prompt or saved instruction that names the old slug stops finding it.
• Exposure survives edits. When you edit and republish an exposed workflow — or apply a template update — the new version stays exposed with the same description. You never need to re-expose after a change.

Turning the switch off removes the workflow from every agent within 30 seconds.

Let an agent build workflows

Agents connected through sign-in can also draft workflows, on a workspace URL or the whole-account URL, if you have an account role, your plan includes authoring, and the connection has the Build permission. Publishing, turning workflows on and off, and exposing them also need Admin (see Choose what a connection can do). The agent works in a real draft — the same one you see in the editor:

1. The agent creates a draft (create_workflow_draft) and gets back an editor link.
2. It searches the app catalog for the steps it needs and reads their schemas (find, describe). It can also read your forms' fields, your tables' columns and your Library's templates, and check whether your app connections still work. It proposes changes (propose_changes), and validates the draft (validate_draft) — every change passes the same validation the in-app AI drafter uses, so the agent cannot save a broken graph.
3. The agent previews the publish (preview_publish): what going live will do — including anything turning the workflow off cannot undo — and the setup steps a person still has to take, each with a link to where they finish it: the workflow's Setup page for connecting an app, otherwise the exact node in the editor.
4. You follow those links to connect apps, attach keys, or pick a phone number. The agent never touches a credential.
5. The agent publishes (publish), then checks the workflow's deployment status with describe until every trigger is live. It can also turn workflows on and off and expose them to assistants (set_workflow_state).

To change a workflow that is already published, the agent opens a draft of it (create_workflow_draft with workflowId), proposes changes and publishes again. The live version keeps running until then. See Change a published workflow.

One connection for every client

An agency doesn't need a connection per client. On the whole-account URL, one sign-in connection builds in any workspace of the account:

• A call about an existing workflow, draft or table works in that item's own workspace. The agent doesn't need to name a workspace for it.
• Making something new, or searching what one workspace can reach (the app catalog, connections, tables), names the workspace with workspace set to its slug. If the account has only one workspace, the agent can leave it out.
• Nothing is guessed. If the account has more than one workspace and the agent leaves workspace out, nothing is created. The call answers with the list of workspaces, so the agent can ask you which client the work is for:

// create_workflow_draft({ "name": "New patient intake" })
{
  "ok": false,
  "code": "invalid-arguments",
  "retryable": true,
  "message": "This account has 2 workspaces. Say which one this workflow is for.",
  "hint": "Ask the person which client this is for, then call create_workflow_draft again with workspace set to that workspace's slug.",
  "details": {
    "workspaces": [
      { "name": "Acme Dental", "slug": "acme-dental" },
      { "name": "Sunrise Spa", "slug": "sunrise-spa" },
    ],
    "truncated": false,
  },
}

Every new draft names the workspace it was created in. A workflow in one client's workspace can only ever use the app connections that workspace can reach. A workspace URL still works as before: it builds in its own workspace only.

An agent can also build a form for a workflow to start from: it creates a draft form (create_workflow_draft with type: "form"), adds its fields (propose_changes), previews it and publishes it (preview_publish and publish), then adds a Form Submission trigger to the workflow. It edits draft forms only, and the workflow can't publish until the form is published. See Build a form.

With Build, the agent can also create tables and change their columns (edit_table), and read, add, change and delete their rows (table_rows). Tables have no draft, so these changes are live as soon as they save. Deleting rows or removing a column takes a confirm step: the first call changes nothing and lists what will be lost, and the assistant is asked to show you that list before it confirms. See Build and fill tables.

Publishing a workflow over MCP applies the same checks as the editor's Publish button: only the person who created the version can publish it, your plan's limits apply, and if your account requires two-factor authentication, the connection must have been made after you verified it (see MCP tools and limits for the reconnect steps).

API keys cannot author or publish. These tools are only available to agents connected through sign-in, so every change is attributed to a real person.

API keys for headless agents

For automation that cannot open a browser to sign in, create a static API key:

1. In AI → Assistants, open the Access tab and select Create key.
2. Scope it to a workspace or the whole account, and choose its Permissions: Read is always on, and Run is on by default — untick it for a key that can only look. Optionally set an expiry date, a daily call cap, and a workflow allowlist. With an allowlist, the key can only reach the listed workflows. A key's permissions can't be changed after it's created.
3. Copy the key when it is shown. It appears exactly once — only a hash is stored, so a lost key means revoking it and creating a new one.

The agent sends the key as a bearer token against the same connection URL.

See what's connected

The Access tab in AI → Assistants lists every credential that has used your account's MCP server: the API keys table, and the Signed-in assistants card with who connected and when each last called something. Revoke an API key from its table; a signed-in agent loses access when you disconnect it from the agent's own settings or the user's access changes.

If it doesn't work

• The agent's connection fails before sign-in — check the URL. Both slugs must match your account and workspace exactly; the settings page is the source of truth.
• find doesn't return a workflow — the workflow needs Expose to AI agents turned on (the ⋯ menu in its editor), it must be published, and your connection's scope must include its workspace. API keys with an allowlist only see listed workflows. Running it with run_workflow also needs the Run permission.
• A call answers that a tool was retired — the assistant is using an old tool list. The answer names the replacement; reconnect the connector to refresh its list. Retired tools lists every old name and what replaced it.
• Calls return rate-limited — you hit the hourly bounds or your plan's daily tool-call budget. The response says when to retry. See MCP tools and limits for the numbers.
• Authoring tools are missing — authoring requires a sign-in connection (not an API key), an account role (someone with only workspace access can't author), and a plan that includes it. The publish tools (preview_publish, publish, set_workflow_state) follow the same rule. On top of that, the draft tools (create_workflow_draft, propose_changes) and the table tools (edit_table, table_rows) need the Build permission, and publish and set_workflow_state need Admin. Both are ticked on the Authorize access screen, so if one is missing, reconnect and tick it. Ask the assistant to call whoami first: if it says the credential, the role, or the plan is what blocks a permission, reconnecting won't help.
• A tool is refused, or you don't know why one is missing — ask the assistant to call whoami. It reports the account and workspace the connection is on, every permission with whether it is usable here and, if not, why (not granted, an API key, your role, or your plan), and the calls left today (not shown to someone with only workspace access). A call to a tool the connection has but lacks the permission for comes back with details.requiredPermission naming it. A tool outside the plan, role, or credential answers that it is not available; whoami says which of those blocks it.
• Publishing is refused with mfa-step-up-required — your account requires two-factor authentication and the connector was added before you verified it. Remove the connector in the assistant, add it again, and complete the two-factor check at sign-in.

Next steps

• MCP tools and limits — every tool, argument, error, and plan limit
• Publish a workflow — get a workflow live so agents can run it
• Webhook triggers — how agent-facing input schemas derive from the fields your workflow uses