Skip to content
SupaCloud Docs
Select themeSelect language

Connect an external MCP coordinator

An external coordinator is any MCP client that drives SupaCloud from the outside — a scheduler, another agent system, or your own automation. It talks to the external MCP gateway (POST /api/mcp, a standard MCP Streamable-HTTP endpoint) with a workspace-scoped API token and sees the same tool surface an in-app coordinator agent uses: run and task reads, backlog, approvals, workflow triggers, task create/cancel/intervene, and single-step reruns.

The API tokens tab in Settings, with the mint form's scope checkboxes and the list of existing tokens by label, status and fingerprint.The API tokens tab in Settings, with the mint form's scope checkboxes and the list of existing tokens by label, status and fingerprint.

  1. Mint a token. Open Settings → Credentials → API tokens (owner or admin). Give the token a label, pick its scopes and create it:

    • mcp:read — the read tier (runs, tasks, backlog, approvals, memories).
    • mcp:ops — the control tier (trigger workflows, create/cancel/intervene on tasks, decide approvals, rerun a failed step, manage schedules).
    • management:read — optional, read-only access to the classic Management API alongside MCP.

    The token value (scmt_…) is shown exactly once — copy it now. Only the fingerprint remains visible afterwards; revoking by fingerprint kills the token immediately.

  2. Point your MCP client at the gateway. Configure it as a Streamable-HTTP server with the URL https://<your-instance>/api/mcp and the header Authorization: Bearer <token>. initialize → tools/list shows exactly the tools your scopes reach; everything else answers with a JSON-RPC method-not-found — the deploy tier is never reachable externally.

  3. Drive the loop. Typical coordinator calls:

    • run.list / run.get / run.events — status, the per-node tree and the per-step event timeline of a run (each workflow node writes started/completed/failed events, including a stdout/stderr tail on failures).
    • task.create / task.intervene / task.cancel — start, steer and stop agent tasks. Budgets and admin closeout rules apply exactly as in the app.
    • approvals.list / approval.decide — see everything waiting, and decide paused-agent tool approvals. A workflow human gate is listed but never decidable by a coordinator: approval.decide refuses it outright, because that gate exists precisely to stop until a person decides. A coordinator can therefore report that a human is needed, and nothing more.
    • backlog.list / backlog.get — the autonomous backlog’s items.
    • run.rerun_node — re-execute one failed workflow step; the run resumes on its own once the step succeeds.

  4. Size the rate limits. The same settings tab carries the workspace’s external limits: reads per tool per hour (default 50) and ops calls per token per hour (default 30). Empty fields keep the defaults; a polling coordinator usually needs more.

    These two limits are per token, so one busy integration cannot starve another’s hourly allowance. Above them sits a workspace-wide ceiling of 100 ops calls per day that every caller shares — your coordinators and the in-app agents draw from the same budget, and raising a token’s hourly number does not raise it. That ceiling is deliberately not settable from the app; on a self-hosted instance an operator can change it with the AGENT_MCP_WORKSPACE_OPS_DAILY_LIMIT environment variable.