> 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.md).

# CARTO MCP Server

The CARTO MCP Server is the fastest way to put the CARTO platform inside your AI assistant. Through the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), agents like Claude, ChatGPT, Gemini Enterprise, and Microsoft Copilot Studio can work with your CARTO account directly in the conversation: explore connected data warehouses, create and edit Builder maps, author and run Workflows, render maps inline, and reach organization admin — all in natural language, over a single URL.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FqMoxcKrAQZUGUHNFswmY%2Fcopilot_edited.gif?alt=media&amp;token=4749644b-0f6c-49bc-9dac-5f198a7f3d2a" alt=""><figcaption></figcaption></figure>

## What your agent can do

Once connected, your agent has a broad set of CARTO tools available. It picks the right one from your natural-language request — you don't need to know tool names.

<table><thead><tr><th width="220">Capability</th><th>What the agent can do</th></tr></thead><tbody><tr><td><strong>Explore data</strong></td><td>List connections, browse and search warehouse tables, inspect column distributions, and locate named sources and saved maps.</td></tr><tr><td><strong>Create &#x26; edit maps</strong></td><td>Build a Builder map from a table or SQL query, restyle layers, add widgets and popups, set privacy, and open the result — reading and updating existing maps in place.</td></tr><tr><td><strong>Build &#x26; run workflows</strong></td><td>Author an analytical workflow (filter, spatial join, group-by, enrich), validate it, run it in sync or async mode, and schedule it.</td></tr><tr><td><strong>Query &#x26; analyze</strong></td><td>Run spatial SQL, geocode addresses, compute isolines and routes, and enrich with the Data Observatory.</td></tr><tr><td><strong>Import &#x26; export</strong></td><td>Bring geospatial files into the warehouse, export results back out, and move data between connections.</td></tr><tr><td><strong>Manage your workspace</strong></td><td>Work with connections, credentials, named sources, and projects — and, for admins, users, org settings, and activity data.</td></tr></tbody></table>

Full per-tool documentation is in the [MCP Tools Reference](/carto-for-agents/mcp-server/tools-reference.md). Your team extends this catalog by [publishing any Workflow as an MCP tool](/carto-user-manual/workflows/workflows-as-mcp-tools.md).

{% hint style="info" %}
Interactive maps render inline only in MCP clients that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview#client-support) — Claude.ai, ChatGPT, and Claude Desktop today. In clients that don't, the map tool returns a text confirmation; ask the agent for the map URL and open it in CARTO instead.
{% endhint %}

## Before you start: enable CARTO AI

The MCP Server lives under CARTO AI, so an Organization Admin must have **CARTO AI enabled** for your org first. It's the organization-wide master switch in **Settings > CARTO AI** — when it's off, no AI capability (the MCP Server included) is available to anyone in the org. See [CARTO AI](/carto-user-manual/settings/carto-ai.md) for how to turn it on. If the **Developers > Workflow API & MCP Server** page below is missing or empty, this is the first thing to check.

## Get your MCP Server URL

Find the **MCP Server URL** in your CARTO Workspace under **Developers > Workflow API & MCP Server** (in the CARTO AI section). It follows this pattern:

```
https://<region>.api.carto.com/mcp/<account_id>
```

If your organization signs in to CARTO through single sign-on (SSO), use the separate **SSO login** URL shown below the standard one. It routes the interactive login through your identity provider, so members authenticate with their SSO credentials:

```
https://<region>.api.carto.com/mcp/sso/<account_id>
```

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-05798533e658761a7335530c6d2a7ed1dd269d3b%2Fmcp-server-url-sso.png?alt=media" alt="The Workflow API &#x26; MCP Server page in CARTO Workspace, showing the Standard login and SSO login MCP Server URLs"><figcaption></figcaption></figure>

{% hint style="warning" %}
Copy the URL from the Workspace rather than assembling it by hand — this is the most common setup mistake. On **self-hosted and dedicated** deployments the path is `https://<your-domain>/api/mcp/<account_id>` (note the `/api/` prefix); a wrong path returns a bare `405 Not Allowed`.
{% endhint %}

## Choose how to authenticate

How you authenticate decides how much of CARTO your agent can use. This is the most important setup decision.

<table><thead><tr><th width="200">Method</th><th>Best for</th><th>What the agent gets</th></tr></thead><tbody><tr><td><a href="/carto-for-agents/mcp-server/connecting-with-oauth.md"><strong>OAuth (U2M)</strong></a></td><td>Interactive clients — Claude, ChatGPT, Gemini, Copilot, Snowflake, Databricks</td><td><strong>The full tool surface</strong>, including creating and editing maps, authoring workflows, and admin. Each person signs in as themselves.</td></tr><tr><td><a href="/carto-for-agents/mcp-server/connecting-with-oauth.md#unattended-access-m2m"><strong>OAuth (M2M)</strong></a></td><td>Unattended, service-to-service access</td><td>The full surface, with no interactive login, via an <a href="/carto-user-manual/developers/managing-credentials/m2m-oauth-clients.md">M2M OAuth client</a>.</td></tr><tr><td><a href="/carto-for-agents/mcp-server/connecting-with-api-tokens.md"><strong>API Access Token</strong></a></td><td>Quick read-and-discovery setups, and hosts that only accept a static token (Oracle)</td><td>A <strong>read-and-discovery</strong> subset that depends on the token's Allowed APIs — browse data, run SQL, poll (not start) Workflow runs, search the Data Observatory. No map or Workflow authoring, no admin.</td></tr></tbody></table>

{% hint style="success" %}
**Rule of thumb:** if the agent should *do* things — build maps, author workflows, administer the org — use **OAuth**. If it only needs to *look at* things, an **API Access Token** is a quick start.
{% endhint %}

**Claude and Claude Code connect with just the URL** — no OAuth client to create, nothing to register. Other clients use a self-service SPA OAuth client. See [Connecting with OAuth](/carto-for-agents/mcp-server/connecting-with-oauth.md).

{% hint style="success" %}
For step-by-step setup on your platform — Claude, ChatGPT, Copilot, Gemini, Snowflake, Databricks, Oracle, and coding agents — see [Connect your platform](/carto-for-agents/connect-your-platform.md).
{% endhint %}

***

## Available tools

The CARTO MCP Server ships with a catalog of built-in tools, organized by category. Your team adds to it by publishing Workflows as MCP tools. Full per-tool documentation, including every parameter, is in the [MCP Tools Reference](/carto-for-agents/mcp-server/tools-reference.md).

<table><thead><tr><th width="240">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, credentials, projects, and activity data.</td></tr></tbody></table>

{% hint style="info" %}
CARTO is expanding the MCP surface over time. If there's a platform capability you'd like exposed as a tool, [get in touch](https://carto.com/contact).
{% endhint %}


---

# 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-for-agents/mcp-server.md?ask=<question>&goal=<endgoal>
```

`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.