Execute actions with Embedded MCP

execute-actions runs published app actions on the end user's connections. A Run Workflows key or higher can call it.

Each actions entry needs a unique ref, appRef, and actionRef. Add arguments from the action schema. Use connectionRef when the user has several accounts for the app. For writes, set idempotencyKey so a retry does not run the same write twice.

{
  "actions": [
    {
      "ref": "send",
      "appRef": "slack",
      "actionRef": "sendMessage",
      "arguments": {
        "channel": "C123",
        "text": "Deployment complete"
      },
      "connectionRef": "cred_public_1",
      "idempotencyKey": "message-123"
    }
  ]
}

{
  "success": true,
  "data": {
    "results": [
      {
        "ok": true,
        "ts": "1727524800.000100"
      }
    ]
  },
  "meta": {
    "resultCount": 1,
    "connectionId": "cred_public_1",
    "page": {
      "nextCursor": null
    }
  }
}

The example output is shortened. The live response can include connection, page, and compaction metadata.

More than one action

Send up to 20 entries. Results use each entry's ref; independent entries run in parallel. If one action needs another's output, make separate calls.

{
  "actions": [
    {
      "ref": "a",
      "appRef": "slack",
      "actionRef": "listChannels"
    },
    {
      "ref": "b",
      "appRef": "hubspot",
      "actionRef": "listContacts"
    }
  ]
}

Before execution, the server resolves and validates every entry. One invalid entry stops the batch before any action runs. A provider failure after execution starts can still leave other entries completed.

Without resultTransformCode, a multi-action result uses data.byRef. For example:

{
  "success": true,
  "data": {
    "byRef": {
      "a": {
        "results": [
          {
            "id": "channel_1"
          }
        ]
      },
      "b": {
        "results": [
          {
            "id": "contact_1"
          }
        ]
      }
    }
  }
}

Use fields to select output field paths. Each entry can use query.filter, query.sort, and query.page when its schema allows them. Page mode is single by default; all drains within server limits. Follow meta.page.nextCursor for another page.

This example requests one filtered page. The field names and operators must match the live action schema:

{
  "actions": [
    {
      "ref": "contacts",
      "appRef": "hubspot",
      "actionRef": "listContacts",
      "query": {
        "filter": {
          "where": [
            {
              "field": "status",
              "operator": "eq",
              "value": "active"
            }
          ]
        },
        "sort": [
          {
            "field": "createdAt",
            "direction": "desc"
          }
        ],
        "page": {
          "mode": "single",
          "size": 25
        }
      }
    }
  ],
  "fields": [
    "id",
    "email"
  ]
}

For large results, read meta.notice and pass meta.compaction.resultSet to query-result-set. Stored results last 30 minutes from the last query. resultTransformCode takes a JavaScript function expression and shapes returned rows; it does not change the provider action.

For one action, the function receives { data } and returns an array. For several actions, it receives { refs, dataByRef, metaByRef }. Use separate calls when later action arguments depend on earlier output.