> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-user-manual/workflows/workflows-as-mcp-tools.md). # Workflows as MCP Tools {% hint style="info" %} For an overview of the CARTO MCP Server itself — how to connect web and CLI agents to it, and the built-in tools it exposes — see [CARTO for Agents → CARTO MCP Server](/carto-for-agents/mcp-server.md). {% endhint %} Workflows are the foundation for creating MCP Tools in CARTO. Each tool exposed through the CARTO MCP Server is powered by a workflow that defines how spatial problems are solved, the data required as input, and the results returned to the AI Agent. This page explains how to configure workflows for MCP, including how to define outputs, write clear tool descriptions, and keep tools in sync as you make updates. By following these steps, you ensure that your AI Agents can reliably use the tools you create to answer geospatial questions. ### Create a Workflow Each MCP Tool is backed by a Workflow. For every type of question or task you want the agent to answer, you will need to create a dedicated Workflow.
### Define the Output Use the **MCP Tool Output** component in Workflows to define the expected output of the tool. * Select **Sync** mode if the workflow returns results immediately. * Select **Async** mode if the workflow requires longer processing time and results are retrieved after execution.
### Writing Descriptions and Enabling the Tool Click on the three-dot options button in the top-right corner to access the MCP Tool dialog.
Once in the dialog: * Write a clear description that explains the purpose of the tool. * Define all input parameters with explicit names and descriptions. * Enable the tool so it can be exposed through the MCP Server. {% hint style="info" %} **Geo parameters**: Variables with the Geo type are exposed as string parameters in the MCP Tool schema. The AI Agent should pass the value as a JSON string containing a GeoJSON FeatureCollection: `{"type":"FeatureCollection","features":[...]}`. Learn more about [Geo variables](/carto-user-manual/workflows/using-variables-in-workflows.md). {% endhint %} #### Propagating Changes When you make updates to a workflow, ensure you **sync** the workflow. This propagates the changes to the MCP Tool so the AI Agent always uses the latest version.
### Execution Settings In the MCP Tool dialog, you can configure how the tool handles repeated executions with the same parameters. * **Reuse output for repeated calls**: When enabled, tool calls with identical parameters will return the cached output table from a previous execution instead of recomputing the workflow. This improves performance for frequently repeated queries. When disabled, the workflow is always recomputed, ensuring fresh results regardless of parameter values. {% hint style="info" %} This setting is independent from the cache settings for Editor UI and API executions. Each execution method can be configured separately. See [cache options](/carto-user-manual/workflows/temporary-data-in-workflows.md#cache-options) for more details. {% endhint %} ### Test your MCP Tool Before exposing a tool to your AI Agents, you can run it exactly as an agent would, directly from the workflow canvas. This lets you preview the response an agent will receive, understand execution timing, and catch errors early — without having to enable the tool and call it from a live agent. {% hint style="info" %} Testing is available to workflow **Editors**. It runs through the same CARTO MCP Server path a real agent uses, so what you see in the test is what an agent gets. {% endhint %} #### Run an MCP Tool test Open the **Run** dropdown in the top-right corner of the canvas and select **Run MCP Tool test**. This option becomes available once your workflow has a title and a configured MCP Tool (enabled or disabled) with a connected **MCP Tool Output** component. If any of these is missing, the option is disabled and a tooltip explains what's required.
#### Provide input parameters Selecting **Run MCP Tool test** opens the **Input parameters** popover in the top-right of the canvas, pre-filled with the default values from the [Variables panel](/carto-user-manual/workflows/using-variables-in-workflows.md). Each parameter is rendered with the control matching its type — a **Text field** for string variables, a **Number field** for number variables, and a **Custom geometry** capture for Geo variables. Edit any value to test different inputs, or use **Reset** to restore the defaults. Clearing a field falls back to that variable's default value. These values are scoped to the test session only: they are not written back to the Variables panel, and they are discarded when you leave test mode (switching the dropdown back to **Run** or **Run (Reuse)** closes the popover).
#### Execute and read the results Click **Run** to execute. The bottom **Messages** tab switches to a split view: * **Run history** (left) lists the test executions in the current session, newest first, each with a status icon (running, success, error, cancelled). Select any run to reload its logs and the inputs used. * **Execution logs** (right) stream the run's progress step by step, ending in the tool's response rendered as expandable JSON with the row count and total execution time. The execution mode is set by your **MCP Tool Output** component: * **Sync** — the response is returned immediately. Steps: *Started → Executing workflows nodes → Fetching Output → Result*. * **Async** — the job is submitted and polled to completion, mirroring the full agent lifecycle. Steps: *Started → Executing workflows nodes → Submitting async workflow job → Polling status → Fetching job results → Result*. You can **Cancel** a run in progress, and **Copy** the full JSON response to share the exact output format with agent developers or reuse it in your tool documentation. {% hint style="info" %} The Run history is kept for the current session only — it is cleared when you reload the page or switch to another workflow. Only MCP Tool test runs appear here; regular **Run** and **Run (Reuse)** executions continue to use the standard Messages view. {% endhint %}
### Provide your Agent with access to Workflows MCP Tools Once Workflows is enabled as an MCP Tool, you can give your Agents in CARTO or outside CARTO access to it. To learn how to connect to the CARTO MCP Server and use your MCP Tools in other MCP-compliant agentic applications, [see this section](/carto-for-agents/mcp-server.md). If you want to provide access to the Workflows MCP Tool to an AI Agent in CARTO, [see this section](/carto-user-manual/ai-agents/working-with-tools.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.carto.com/carto-user-manual/workflows/workflows-as-mcp-tools.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.