Skip to content

Quickstart

Two short paths: trigger a workflow over HTTP, and connect an AI client to the MCP server. The examples use the demonstration workspace jaffleshop and placeholder credentials. Replace them with your own workspace identifier, ids and token.

Trigger a workflow and read the result

1. Create a token. In the application, open the workflow, go to its API access panel and create a token. Copy it; it is shown once.

export RIG_TOKEN="rig_mcp_jaffleshop_EXAMPLE"
export RIG_HOST="https://app.rig.so"   # the host you sign in at: see Base URLs
export RIG_BASE="$RIG_HOST/jaffleshop"

RIG_HOST is the base URL for your workspace's region, or your dedicated deployment's hostname. See Base URLs.

2. Start a run.

curl -X POST "$RIG_BASE/workflows/WORKFLOW_ID/triggers/api" \
  -H "Authorization: Bearer $RIG_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"input_data": {}}'

input_data holds the workflow's trigger inputs. The empty object works only for a workflow with no required inputs; otherwise fill in the fields its trigger defines, or the request is rejected with invalid_input_schema. Each new run needs a new Idempotency-Key. Reuse a key only to retry the same request, which returns the original run instead of starting another.

{
  "execution_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
  "status": "running",
  "trigger_type": "api",
  "poll_url": "/jaffleshop/workflows/WORKFLOW_ID/runs/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
  "started_at": "2030-01-31T09:00:00+00:00"
}

3. Poll until the run completes.

curl "$RIG_BASE/workflows/WORKFLOW_ID/runs/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee" \
  -H "Authorization: Bearer $RIG_TOKEN"

When status is completed, the result is in final_context. When it is failed, the reason is in error_message.

The full contract, including idempotency, concurrency and error codes, is in Webhooks and callbacks.

Connect an AI client over MCP

1. Add the server to your client. For Claude Code:

claude mcp add --transport http --callback-port 19876 rig "$RIG_HOST/mcp/jaffleshop/"

Other clients are covered in MCP server.

2. Sign in. The client opens a browser window the first time it connects.

3. Ask a question. The client can now call Rig's tools. A typical sequence for a data question is:

  1. get_business_context for a primer on the workspace and its areas.
  2. search_tables and search_metrics to find the relevant tables and any certified metric.
  3. get_table_columns and get_usage_rules for the tables it chose.
  4. test_sql to validate a query against sample data, then execute_sql to run it.

To call the server from a script instead, send an API token with the mcp scope, as shown in Connecting with a token. The workflow token created above has no mcp scope unless you ticked Also allow MCP access when creating it, and the MCP server rejects a token without that scope.