> 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-for-agents/mcp-server/tools-reference.md).

# MCP Tools Reference

The CARTO MCP Server exposes a catalog of built-in tools an agent calls to explore data, work with maps and Workflows, and administer your organization. Related operations are grouped into a single tool that takes a discriminator parameter — for example, `explore_data` handles listing connections, browsing tables, searching, and describing columns through one `method` argument. This keeps the catalog compact so it fits comfortably inside every host's tool limit.

You don't call these tools by hand. Your agent picks the right tool and parameters from your natural-language request; this reference is here so you understand what the agent can do and can reason about its actions.

## Categories

<table><thead><tr><th width="220">Category</th><th>What it covers</th></tr></thead><tbody><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/maps-tools.md"><strong>Maps tools</strong></a></td><td>Create, update, validate, read, and render Builder maps.</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workflow-tools.md"><strong>Workflow tools</strong></a></td><td>Create, run, schedule, and inspect Workflows, plus any your team publishes as MCP tools.</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md"><strong>Data tools</strong></a></td><td>Explore connections and tables, run SQL, geocode, route, import/export, and enrich with the Data Observatory.</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workspace-tools.md"><strong>Workspace tools</strong></a></td><td>Manage users, connections, credentials, projects, customizations, and activity data.</td></tr></tbody></table>

## How the tools are described

Each tool entry lists:

* **What it does** and when the agent uses it.
* Its **method** (or `operation` / `kind`) parameter, if it groups several operations, with the available values.
* The **key parameters** the agent supplies. Full parameter details — including optional fields and provider-specific options — live in each tool's own MCP description, which the agent reads at call time.
* Whether the tool is **read-only** or can **modify or delete** data. CARTO annotates every tool so hosts that ask for confirmation before destructive actions can do so.

## Which tools an agent can use

Which tools an agent sees is decided at three layers:

1. **How it authenticated.** Over an [API Access Token](/carto-for-agents/mcp-server/connecting-with-api-tokens.md), the agent gets a read-and-discovery subset that grows with the token's Allowed APIs, such as browsing data, running SQL, polling Workflow runs and searching the Data Observatory. Authoring and admin tools aren't offered. See [What a token unlocks](/carto-for-agents/mcp-server/connecting-with-api-tokens.md#what-a-token-unlocks) for the exact breakdown. Over [OAuth](/carto-for-agents/mcp-server/connecting-with-oauth.md), the agent sees the tools the signed-in user's role allows; the table below shows which.
2. **What your team publishes.** Your team decides which Workflows become MCP tools and what inputs each accepts. See [How published tools are governed](/carto-for-agents/mcp-server/tools-reference/workflow-tools.md#how-published-tools-are-governed).
3. **Your MCP client.** Most clients let an administrator enable or disable individual tools per connected server, on your side.

The model reads each tool's description to decide when to call it. Built-in descriptions ship with CARTO releases; Workflow-tool descriptions are written by your own editors when they publish.

### What each role sees over OAuth

Tools are grouped, so a tool with several methods may appear with fewer of them for a given role, and disappears when none are left.

<table><thead><tr><th width="420">Tool</th><th>Admin</th><th>Editor</th><th>Viewer</th></tr></thead><tbody><tr><td><strong>Maps</strong></td><td></td><td></td><td></td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/maps-tools.md#create_map"><code>create_map</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/maps-tools.md#update_map"><code>update_map</code></a></td><td>✓</td><td>✓</td><td>–</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/maps-tools.md#read_maps"><code>read_maps</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/maps-tools.md#validate_map"><code>validate_map</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/maps-tools.md#view_map"><code>view_map</code></a></td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td><strong>Workflows</strong></td><td></td><td></td><td></td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workflow-tools.md#create_workflow"><code>create_workflow</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/workflow-tools.md#update_workflow"><code>update_workflow</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/workflow-tools.md#schedule_workflow"><code>schedule_workflow</code></a></td><td>✓</td><td>✓</td><td>–</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workflow-tools.md#read_workflows"><code>read_workflows</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/workflow-tools.md#validate_workflow"><code>validate_workflow</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/workflow-tools.md#read_workflow_components"><code>read_workflow_components</code></a></td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workflow-tools.md#run_workflow"><code>run_workflow</code></a></td><td>✓</td><td>✓</td><td><code>status</code> and <code>results</code> only</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workflow-tools.md#your-published-workflows">Your published Workflow tools</a></td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td><strong>Data</strong></td><td></td><td></td><td></td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#manage_connections"><code>manage_connections</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#import_data"><code>import_data</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#transfer_data"><code>transfer_data</code></a></td><td>✓</td><td>✓</td><td>–</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#explore_data"><code>explore_data</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#execute_query"><code>execute_query</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#execute_async_query"><code>execute_async_query</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#export_data"><code>export_data</code></a></td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#geocode"><code>geocode</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#route"><code>route</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#calculate_isolines"><code>calculate_isolines</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#calculate_od_matrix"><code>calculate_od_matrix</code></a></td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#search_data_observatory"><code>search_data_observatory</code></a></td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#manage_named_sources"><code>manage_named_sources</code></a></td><td>✓</td><td>✓</td><td>–</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/data-tools.md#manage_data_observatory_subscriptions"><code>manage_data_observatory_subscriptions</code></a></td><td>✓</td><td>no <code>unsubscribe</code></td><td>no <code>unsubscribe</code></td></tr><tr><td><strong>Workspace</strong></td><td></td><td></td><td></td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#manage_api_access_tokens"><code>manage_api_access_tokens</code></a></td><td>✓</td><td>✓</td><td>–</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#manage_oauth_clients"><code>manage_oauth_clients</code></a>, <a href="/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#organize_projects"><code>organize_projects</code></a></td><td>✓</td><td>✓</td><td>read only</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#manage_users"><code>manage_users</code></a></td><td>✓</td><td><code>list</code> only</td><td><code>list</code> only</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#admin_carto"><code>admin_carto</code></a></td><td>✓</td><td>read only</td><td>read only</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#admin_carto_customizations"><code>admin_carto_customizations</code></a></td><td>✓</td><td>read only</td><td>read only</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#export_activity_data"><code>export_activity_data</code></a></td><td>✓</td><td>–</td><td>–</td></tr><tr><td><a href="/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#delete"><code>delete</code></a></td><td>✓</td><td>✓</td><td>–</td></tr><tr><td><code>get_workspace_info</code></td><td>✓</td><td>✓</td><td>✓</td></tr></tbody></table>

Superadmin-only tools ([`superadmin_carto_resources`](/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#superadmin_carto_resources)) aren't offered to Admins. This table shows what the agent is offered; each call is still checked against your CARTO permissions when it runs.

## Extend the catalog with your own Workflows

Any Workflow your organization builds can be published as an MCP tool, registering alongside the built-in tools. See [Workflow tools](/carto-for-agents/mcp-server/tools-reference/workflow-tools.md#your-published-workflows) and [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.carto.com/carto-for-agents/mcp-server/tools-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.