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 — draft new workflows that open in the visual editor for you to finish and publish.

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 MCP settings

   Go to Settings → Integrations → AI agents (MCP). You need an account admin or owner role. The page lists one URL per workspace plus a whole-account URL.

   Workspace admins can also copy their workspace's URL from Workspace settings → General, on the AI agents (MCP) card.

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:

   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 and approve the connection on the consent screen — it names the client app and what it is asking for.

   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.

4. Confirm the tools appear

   Ask the agent to list its TaskJuice tools. You should see list_workflows, run_workflow, and get_run at minimum. Workflows you have exposed as tools appear as their own entries named <prefix><workflow-slug> — taskjuice_ by default, or your own prefix if you have a connector domain.

Expose a workflow as a tool

Workflows are not visible to agents by default. 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 when deciding whether the tool fits a task, so describe what the workflow does and what input it expects. Leave it blank and agents see the fallback text shown in the field.

3. Check the tool name and input

   The dialog shows the exact tool name agents will call — your account's tool prefix (taskjuice_ unless you have a connector domain) plus a name derived from the workflow's title. If another exposed workflow shares the title, both names get a distinguishing suffix, so exposing or hiding one can change the other's tool name. The Input line shows what the tool 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. Every exposed tool also carries a ready-made example payload, 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 tool name tracking the workflow title, and they are worth knowing before you rely on a name:

• Renaming the workflow renames its tool. Any agent, prompt, or saved instruction that referenced the old name 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, if your plan includes authoring. 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 looks up apps and node schemas (ground_apps, describe_node), 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. You open the editor link, connect any apps the draft needs, review, and publish. Connecting accounts and publishing always happen in the app, never from the agent.

API keys cannot author. Drafting is 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 Settings → Integrations → AI agents (MCP), select Create key.
2. Scope it to a workspace or the whole account, and optionally set an expiry date, a daily call cap, and a workflow allowlist. With an allowlist, the key can only see and run the listed workflows.
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 Connected clients card on the MCP settings page lists every client app and credential that has used your account's MCP server recently: signed-in agents (with the client app that connected), API keys, when each was last seen, and how many calls it made. Revoke an API key from the table above it; 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.
• tools/list is empty or missing 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.
• 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 workspace-scoped URL, a sign-in connection (not an API key), and a plan that includes it.

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