Workflows tools

CARTO Workflows lets your team package data preparation and analytical pipelines as MCP Tools that any agent connected to the MCP Server can call. Workflows tools complement the built-in platform and interactive tools by exposing organization-specific logic (site selection, trade-area analysis, demand modeling, anything your team has built) in a form an agent can use.

Workflows tools come in two execution modes:

• Sync. The tool returns results immediately. Best for lightweight, fast queries.

• Async. The tool kicks off a job and returns a jobId. The agent then polls async_workflow_job_get_status_v1_0_0 until the job is done, and retrieves the output with async_workflow_job_get_results_v1_0_0. Best for long-running pipelines.

Publish your own workflow as an MCP tool

Any workflow your organization builds in CARTO Workflows can be exposed as an MCP tool by adding the descriptions, inputs, and outputs that the MCP specification expects. For step-by-step guidance, see the Workflows as MCP Tools documentation in the CARTO User Manual.

Best practices

To ensure reliable performance and accurate results when exposing Workflows as MCP Tools, consider the following guidelines:

• Keep tool descriptions clear and specific. Write concise descriptions that explain what the tool does and when it should be used. This helps the agent choose the right tool.

• Define inputs precisely. Use descriptive names and types for all parameters. Avoid ambiguous labels that could confuse the agent.

• Test workflows thoroughly. Run workflows manually before exposing them to confirm that the outputs match expectations.

• Choose the right output mode. Use Sync for lightweight, fast queries; use Async for long-running processes.

• Version and update carefully. When making changes to workflows, sync updates promptly and communicate changes to relevant users of the MCP Server.

• Monitor usage and errors. Track how tools are used and review errors to refine workflows or adjust descriptions as needed.

With Async mode, the agent must poll for status and make an additional call to retrieve results when the job completes. Implementing this control flow in your agent's prompt may require additional work.

---

Async job tools

The two tools below are how the agent drives an async workflow once it has been launched. They are built in to every MCP Server. You don't need to configure them.

async_workflow_job_get_status_v1_0_0

Description

Gets the status of an async workflow job. Use this after calling an async workflow tool that returns a job ID. Poll this tool until the job status is success or failure.

Input properties

Parameter	Type	Required	Description
jobId	string	Yes	The ID of the async workflow job (returned by the workflow tool that launched it).
connectionName	string	Yes	The name of the connection used by the workflow.

Output

A JSON object containing the job status and metadata. Possible status values: pending, running, success, failure, cancelled.

Response example

{
  "status": 200,
  "data": {
    "jobId": "abc-123",
    "connectionName": "carto_dw",
    "providerId": "bigquery",
    "status": "running",
    "error": null,
    "createdAt": "2024-06-20T14:30:00.000Z"
  }
}

Example

After launching an async workflow that returned jobId: "abc-123":

async_workflow_job_get_status_v1_0_0({
  jobId: "abc-123",
  connectionName: "carto_dw"
})

---

async_workflow_job_get_results_v1_0_0

Description

Retrieves the results of an async workflow job after it has completed with success status. Call this only after async_workflow_job_get_status_v1_0_0 confirms the job is done.

Input properties

Parameter	Type	Required	Description
jobId	string	Yes	The ID of the async workflow job.
providerId	string	Yes	The data warehouse provider. One of: bigquery, snowflake, databricks, postgres, redshift, oracle.
connectionName	string	Yes	The name of the connection used by the workflow.
workflowOutputTableName	string	Yes	The fully qualified name of the workflow output table.

Output

A JSON object containing the query results from the workflow output table. The rows array contains the actual data, and schema describes the column types.

Response structure

{
  "status": 200,
  "data": {
    "rows": [
      {
        "store_id": 1,
        "name": "Madrid Centro",
        "trade_area_geom": "POLYGON((-3.71 40.41, ...))",
        "drive_time_min": 10
      },
      {
        "store_id": 2,
        "name": "Madrid Norte",
        "trade_area_geom": "POLYGON((-3.69 40.48, ...))",
        "drive_time_min": 10
      }
    ],
    "schema": [
      { "name": "store_id", "type": "INT64" },
      { "name": "name", "type": "STRING" },
      { "name": "trade_area_geom", "type": "GEOGRAPHY" },
      { "name": "drive_time_min", "type": "INT64" }
    ]
  }
}

Example

After confirming the job completed successfully:

async_workflow_job_get_results_v1_0_0({
  jobId: "abc-123",
  providerId: "bigquery",
  connectionName: "carto_dw",
  workflowOutputTableName: "my_project.results.trade_areas"
})