Workspace API and MCP

Scopes

Grant the smallest set your integration needs. Missing scope returns 403 with a message naming the required scope. Keys are configured in the product by ticking capability groups; each maps to the granular scopes below.

• Task board: tasks:read (list tasks, get one task with comments), tasks:create, tasks:update, tasks:delete, tasks:comments:write (same comment pipeline as the in-app task board, including notifications when applicable).
• Agents: agents:read (list agents and metadata), agents:ping (pulse wake with optional message), agents:heartbeat (short online check via the agent runtime), agents:message (dedicated API chat session per key and agent; counts against workspace usage like in-app chat).

REST API reference

Successful responses are JSON with ok: true and a payload; errors use ok: false plus error and optional code. Validation issues may include an issues array from the schema layer.

• GET /api/ext/v1/status — connectivity and key metadata (no extra scope).
• GET /api/ext/v1/tasks — tasks:read. Returns tasks and snapshot.updatedAt when sourced from snapshot read models.
• POST /api/ext/v1/tasks — tasks:create. Body: title (required), optional description, status, priority, requiresApproval, storyPoints (nullable), projectId (nullable), assigneeIds, dueAt (ISO datetime or null).
• GET /api/ext/v1/tasks/:id — tasks:read. Returns task, comments, snapshot metadata.
• PATCH /api/ext/v1/tasks/:id — tasks:update. Body may include any of: title, description, status, priority, requiresApproval, storyPoints, projectId, assigneeIds, subscriberIds, docIds, dueAt.
• DELETE /api/ext/v1/tasks/:id — tasks:delete.
• POST /api/ext/v1/tasks/:id/comments — tasks:comments:write. Body: content (required), optional author (defaults to api).
• GET /api/ext/v1/agents — agents:read.
• POST /api/ext/v1/agents/:id/ping — agents:ping. Optional JSON body: message (wake text).
• POST /api/ext/v1/agents/:id/heartbeat — agents:heartbeat. Optional JSON body: prompt (defaults to a short online confirmation).
• POST /api/ext/v1/agents/:id/message — agents:message. Body: text. Disabled agents return 404 as not found.

Webhooks

Optional HTTPS URL per key. On task lifecycle events the runtime POSTs a JSON envelope (event name, tenant id, key id, timestamp, payload).

If you configure a signing secret, verify header X-SAT-Signature: sha256=<hex HMAC-SHA256 of the raw body>.

Subscribe per event: task.created, task.updated, task.deleted, task.comment.created, or * for all. Delivery is best-effort with a short timeout—design your endpoint to be idempotent.

Key management and audit (session auth)

While signed in as the workspace owner on the same origin, use session-authenticated routes (not the Bearer key): GET and POST /api/workspace-api/keys, PATCH /api/workspace-api/keys/:id, DELETE to revoke.

GET /api/workspace-api/audit?limit=… returns a read-only tail of external requests: method, path, status, key label, client IP, duration—useful for compliance and debugging.

Per-key policy and operator controls

• IP allowlist: optional exact IPs or IPv4 CIDRs. Other clients get 403 WORKSPACE_API_IP_DENIED. The runtime uses the first hop of X-Forwarded-For when present (typical behind Cloud Run or a reverse proxy).
• Rate limit: configurable requests per minute per key, enforced in rolling one-minute windows; exceeded returns 429 WORKSPACE_API_RATE_LIMIT.
• Operator disable: when the tenant runtime sets the workspace external API disabled flag, both REST and MCP return 503 with a service-unavailable message.
• Operators may also set a default RPM for new keys; key pepper material for hashing is configured server-side.

HTTP status and error codes

• 400 — invalid JSON body or schema validation (issues may be included).
• 401 — missing Bearer token, invalid secret, or revoked key.
• 402 — PLAN_LIMIT_REACHED on agent heartbeat or message when workspace usage limits apply.
• 403 — WORKSPACE_API_PREMIUM_REQUIRED (free plan), WORKSPACE_API_IP_DENIED (allowlist), WORKSPACE_API_MCP_DISABLED (MCP off for key), or missing scope (explicit scope name in message).
• 404 — task or agent not found where applicable.
• 405 — wrong HTTP method (for example GET on /api/ext/mcp).
• 429 — WORKSPACE_API_RATE_LIMIT.
• 503 — Workspace API disabled by operator on this runtime.

Examples (REST)

curl -sS -H "Authorization: Bearer sat_wk_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"title":"From API","status":"todo"}' \
  "https://YOUR_WORKSPACE_HOST/api/ext/v1/tasks"

curl -sS -H "Authorization: Bearer sat_wk_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"content":"Ship checklist is green."}' \
  "https://YOUR_WORKSPACE_HOST/api/ext/v1/tasks/TASK_ID/comments"

curl -sS -X PATCH -H "Authorization: Bearer sat_wk_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}' \
  "https://YOUR_WORKSPACE_HOST/api/ext/v1/tasks/TASK_ID"

Model Context Protocol (MCP)

Your workspace runtime acts as an MCP server: clients such as Cursor, Claude Desktop, or custom automation connect inbound to POST https://YOUR_WORKSPACE_HOST/api/ext/mcp using Streamable HTTP in stateless mode (no server-side MCP session stickiness), which fits multi-instance Cloud Run.

Use the same Bearer token as REST. Additionally, each key has an MCP enable flag; if MCP is off, POST returns 403 with code WORKSPACE_API_MCP_DISABLED. Rate limits and IP allowlists apply to MCP the same as REST.

Only POST is supported on /api/ext/mcp. GET and DELETE return 405.

Each JSON-RPC request builds a fresh MCP server that registers tools from your scopes. Tool results return structured data as JSON strings in standard MCP text content blocks for easy parsing.

Scopes and tools

Tools are registered from the same scopes as REST (configure them on the API key). See the REST API tab for the full scope list and what each permission allows.

MCP tools and scope mapping

Tool names are stable snake_case. Behavior matches the REST route of the same feature unless noted.

• workspace_status — always available; same data as GET /api/ext/v1/status plus mcpEnabled on the key.
• tasks_list — tasks:read → GET /api/ext/v1/tasks.
• task_get — tasks:read; arguments: taskId → GET /api/ext/v1/tasks/:id.
• task_create — tasks:create; arguments match POST /api/ext/v1/tasks body.
• task_update — tasks:update; arguments: taskId, patch (object) → PATCH /api/ext/v1/tasks/:id.
• task_delete — tasks:delete; arguments: taskId → DELETE /api/ext/v1/tasks/:id.
• task_add_comment — tasks:comments:write; arguments: taskId, content, optional author → POST comments.
• agents_list — agents:read → GET /api/ext/v1/agents.
• agent_ping — agents:ping; arguments: agentId, optional message.
• agent_heartbeat — agents:heartbeat; arguments: agentId, optional prompt.
• agent_message — agents:message; arguments: agentId, text.

Connecting an MCP client

Configure your client with the MCP URL and an Authorization header (or whatever your client maps to custom headers). Exact config file shapes differ by product; refer to your client’s Streamable HTTP or remote MCP documentation.

{
  "url": "https://YOUR_WORKSPACE_HOST/api/ext/mcp",
  "headers": {
    "Authorization": "Bearer sat_wk_live_YOUR_SECRET"
  }
}

Not the same as agent MCP connectors

• Inbound Workspace MCP (this tab): external tools and IDEs call your tenant runtime.
• Outbound MCP connectors in the product UI: agents call an external MCP server you configure in secrets. Different feature, different trust boundary.

Policy and errors

IP allowlist, per-key RPM, operator disable, premium plan checks, and audit behavior are the same as for REST. For the full status and error table, open the REST API tab.

• 403 WORKSPACE_API_MCP_DISABLED — MCP is not enabled for this key (toggle in Workspace API key settings).
• 405 — GET or DELETE on /api/ext/mcp (only POST is valid).