MCP tools and limits
Every tool the TaskJuice MCP server exposes, its arguments, its errors, and the per-plan call budgets.
The server exposes at most 16 tools per connection: the fixed tools below, plus one taskjuice_<workflow-slug> tool per workflow you have exposed, newest first.
Run tools
Available to sign-in connections and API keys.
| Tool | Arguments | Returns |
|---|---|---|
list_workflows | status?, query?, limit? (≤ 50) | Runnable workflows with slug, name, description, and a one-line input summary. query matches the name; status: "draft" requires authoring access. |
describe_workflow | workflowSlug | The full input schema (derived from the trigger, or a permissive fallback marked inputSchemaSource: "fallback"), description, and activation time. |
run_workflow | workflowSlug, input?, idempotencyKey? | Waits up to 25 seconds. A finished run returns its output; a longer run returns {status: "running", runId} — follow up with get_run. |
get_run | runId | Run status, per-step progress, and — once completed — the output. |
list_runs | workflowSlug?, status?, limit? (≤ 50) | Recent runs, newest first. |
taskjuice_<slug> | The workflow's own input fields | Same behavior as run_workflow for that one workflow — a convenience the agent can pick by name. |
Details worth knowing:
inputis the trigger payload. Whatever the agent passes arrives at the workflow exactly as a webhook body would.describe_workflowshows the expected shape.idempotencyKeyprevents double runs. The same key from the same connection within 24 hours returns the original run instead of dispatching again. Use it whenever an agent might retry.- Outputs are capped at 256 KB. Larger outputs come back truncated with
outputTruncated: true; the full result stays in the run detail view. - Two workflows with the same name get distinct slugs suffixed with the workflow id's first 8 characters, so tool names never collide.
Authoring tools
Available only to sign-in connections on a workspace URL, on plans that include authoring.
| Tool | Arguments | Returns |
|---|---|---|
create_workflow_draft | name, description? | A new empty draft: ids, the draft's graph hash, and an editor link. |
get_draft | workflowId | The draft graph, its hash (the base for propose_changes), validation state, unconnected apps, and the editor link. |
propose_changes | workflowId, changeSet, baseGraphHash? | Applies a change-set all-or-nothing. Rejections list every violation; success persists and returns the new graph hash. |
validate_draft | workflowId | Judges the draft against the same gate the in-app drafter uses: green with any apps still needing connections, or the blocker. |
describe_node | canonical | One node's configuration schema. An unknown canonical returns found: false with a ground_apps hint — not an error. |
ground_apps | appSlugs (≤ 10) | Loads app catalogs for proposing nodes, with per-app connection status. Unknown slugs come back in unknownSlugs. |
preview_mapping | expression, sampleOutput, bindings? | Evaluates a JSONata mapping against sample data and returns the output plus warnings. |
Two rules hold everywhere: agents propose, the platform validates — an invalid change never persists — and connecting accounts or publishing always happens in the app, from the editor link the draft carries.
Errors
Every tool failure is a structured result with a code, a message, a retryable flag, and usually a hint naming the fix.
| Code | Meaning | Retry? |
|---|---|---|
invalid-arguments | An argument failed validation; the message names the field. | Yes, corrected |
not-found | No such workflow, run, or draft in this connection's scope. | No |
entitlement-denied | The tool isn't available to this connection (plan, key capability, scope). | No |
rate-limited | An hourly bound or the daily budget was hit. | Yes, after the hint's backoff |
run-refused | The platform declined to start the run (limits, safety, disabled workflow). | Not this session |
proposal-rejected | The change-set violated the workflow schema; every violation is listed. | Yes, corrected |
stale-draft | The draft changed since the hash you proposed against. | Yes — re-read with get_draft and rebase |
compile-refused | validate_draft found a blocker; the message names it. | Yes, after repairing the draft |
payload-too-large | Tool arguments exceeded 256 KB. | Yes, smaller |
Limits
Tool calls are counted per account per day, shared across every connection and key — adding credentials never adds budget.
| Plan | Tool calls per day |
|---|---|
| Starter | 1,000 |
| Growth | 5,000 |
| Scale | 20,000 |
On top of the daily budget, hourly bounds protect against runaways: 10,000 calls per account, and per-credential class caps (3,000 reads, 600 runs, 600 authoring calls, 300 mapping previews). An API key's optional daily call cap bounds that key's share of the account budget — it lowers what one key can spend, never raises the total.
Authoring availability by plan: Starter includes run tools only; Growth and Scale include authoring.
Workflow runs started through MCP are normal runs — they appear in run history and count toward your plan's usage like any other run.
Next steps
- Connect an AI agent with MCP — setup, exposing workflows, API keys
- Usage and overage — how runs are metered and billed