Tool Reference

run_workflow

Start a workflow run (async).

Start a workflow run (asynchronous). Returns a runId immediately. The workflow executes in the background — poll get_run_status with the returned runId until status is "completed", "partial_complete", or "failed".

This is a mutating tool subject to the stricter rate limit of 10 requests/minute.

Parameters

Parameter Type Required Description
workflowId string Yes The workflow ID to run. Use list_workflows to see available IDs.
configuration object No Optional configuration passed to the workflow agents. Can include a "context" string with additional instructions.
companyId string Auto-injected Injected from your API key. Do not pass this.

Available Workflow IDs

ID Name Credit Cost Duration
ai_shop_checkup AI Shop Checkup 25 3-5 min
fix_visibility Fix My Visibility 20 4-6 min
competitive_scan Conquest Campaign 20 3-5 min
content_refresh Service Menu Update 15 4-6 min
full_service Full Detail 45 8-12 min
reputation_shield Reputation Shield 15 2-3 min

Example Request

curl -X POST https://socialcrm.com/api/mcp-app \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "run_workflow",
      "arguments": {
        "workflowId": "ai_shop_checkup",
        "configuration": {
          "context": "Focus on brake service and oil change queries."
        }
      }
    }
  }'

Example Response

Parsed from result.content[0].text:

{
  "runId": "run_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "workflowId": "ai_shop_checkup",
  "workflowName": "AI Shop Checkup",
  "status": "pending",
  "creditsReserved": 25,
  "estimatedDuration": "3-5 min",
  "_hint": "Poll get_run_status with this runId to track progress. Status will transition from pending → running → completed."
}

Output Schema

Field Type Description
runId string Unique identifier for this run. Use with get_run_status.
workflowId string The workflow that was started
workflowName string Human-readable workflow name
status string Initial status, always "pending"
creditsReserved number Credits reserved for this run
estimatedDuration string Expected completion time
_hint string Guidance on next steps

Pre-Flight Validations

Before starting the workflow, the API checks:

  1. Workflow exists — the workflowId must be valid.
  2. Plan access — the workflow must be available on your current plan.
  3. Concurrent run limit — you must not exceed your plan's max concurrent runs.
  4. Credit balance — you must have enough available credits.

If any check fails, the tool returns an error (code -32000) with a descriptive message.

Notes

  • Workflows are asynchronous. The run_workflow call returns immediately with a runId.
  • Poll get_run_status at 5-10 second intervals to check progress. Do not poll more frequently to avoid hitting rate limits.
  • Status transitions: pending → running → completed | partial_complete | failed.
  • Credits are reserved at launch and consumed on completion. Cancelled or failed runs do not consume credits.