> 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/connecting-with-oauth.md).

# Connecting with OAuth

OAuth is the recommended way to connect. It gives your agent the **full tool surface** — creating and editing maps, building and running Workflows, and more — and signs each person in as themselves, so CARTO logs the real user.

How much setup you do depends on your client. Some connect with nothing but the URL. Others need a one-time OAuth client you create in CARTO. Both paths are below.

{% hint style="info" %}
Looking for setup steps for a specific platform? See [Connect your platform](/carto-for-agents/connect-your-platform.md). This page explains the shared OAuth mechanics behind those guides.
{% endhint %}

## The simplest path: clients that support CIMD

Some clients register themselves with CARTO automatically through a **Client ID Metadata Document (CIMD)**, so there's nothing to create — no OAuth client, no secret, no callback to register. Today CARTO recognizes CIMD for **Claude.ai, Claude Desktop, and Claude Code**; other clients (ChatGPT, Copilot Studio, Gemini, and the rest) take the one-time-client path below.

For a CIMD client:

1. Copy your **MCP Server URL** from **Developers > Workflow API & MCP Server**.
2. Add it as an MCP server in the client.
3. When prompted, log in to CARTO to authorize.

That's it. See the [Claude guide](/carto-for-agents/connect-your-platform/claude.md) for the exact clicks.

{% hint style="info" %}
CIMD is a client capability, not a CARTO setting. If a non-Claude client offers a "dynamic registration" or "CIMD" option, it will fail against CARTO today — choose the manual **User-Defined OAuth Client** option and follow the steps below instead.
{% endhint %}

## Everything else: a one-time OAuth client

Other clients — ChatGPT, Copilot Studio, Gemini, Snowflake, Databricks, and more — connect with a **SPA OAuth client** you create once in CARTO. It's self-service; you don't need a CARTO ticket. There are three short steps.

### 1. Create the client in CARTO

In **Developers > Credentials**, open the **SPA OAuth Clients** tab and click **Create new > SPA OAuth Client**. Give it a name, then copy its **Client ID** and **Client Secret**.

### 2. Enter the OAuth settings in your client

In your AI platform's MCP setup, choose OAuth and fill in these values:

| Field              | Value                                                 |
| ------------------ | ----------------------------------------------------- |
| MCP Server URL     | from **Developers > Workflow API & MCP Server**       |
| Client ID / Secret | from step 1                                           |
| Authorization URL  | `https://auth.carto.com/authorize`                    |
| Token URL          | `https://auth.carto.com/oauth/token`                  |
| Scopes             | `openid profile email read:workflows write:workflows` |

### 3. Register the callback URL back in CARTO

Your client will show you a **redirect (callback) URL** — usually only after you've saved the OAuth settings. Copy it, return to your SPA client in CARTO, turn off **"Use default logout/callback URLs and Origins"**, and paste it into **Allowed Callback URLs**. Save, then finish signing in.

That last step is the one people miss. If sign-in fails with **"Callback URL mismatch,"** the URL isn't registered, or doesn't match exactly (no wildcards).

{% hint style="success" %}
The per-platform guides give you each client's exact callback URL and any quirks, so you don't have to hunt for it. Start there: [Connect your platform](/carto-for-agents/connect-your-platform.md).
{% endhint %}

<details>

<summary>Callback URLs for common clients</summary>

| Client            | Callback URL                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| ChatGPT           | `https://chatgpt.com/connector/oauth/<id>` (read `<id>` from the authorize URL)                                     |
| Snowflake         | `https://identity.snowflake.com/oauth2/callback` (fixed — register up front)                                        |
| Gemini Enterprise | `https://vertexaisearch.cloud.google.com/oauth-redirect` (fixed — use it as the SPA client's Application Login URL) |
| Databricks        | `https://<workspace-host>/login/oauth/http.html` (per workspace)                                                    |
| MCP Inspector     | `http://localhost:8000/callback`                                                                                    |
| MCP Jam           | `http://127.0.0.1:6274/oauth/callback/debug`, `http://127.0.0.1:6274/oauth/callback`                                |

The field accepts a comma-separated list, so one client can serve several platforms.

</details>

## What signing in grants

You authorize the platform to use the CARTO MCP Server on your behalf — exploring your data, creating and editing maps, running your Workflows, and (with the right permissions) reaching workspace and admin tools. The token inherits your own CARTO permissions: the connections, datasets, and maps your account can access. Revoke it any time from **Developers > Credentials > SPA OAuth Clients**, or from your platform's connector settings.

## SSO and self-hosted

* **SSO.** If your organization signs in to CARTO through single sign-on, copy the **SSO login** URL from **Developers > Workflow API & MCP Server** instead of the standard one, so login routes through your identity provider.
* **Dedicated or self-hosted.** Swap `auth.carto.com` for your own auth domain. You can confirm it at `https://<your-domain>/.well-known/oauth-protected-resource/api/mcp/<account_id>`.

## Unattended access (M2M)

For service-to-service access with no interactive login, use a **machine-to-machine OAuth client**:

1. In **Developers > Credentials**, open the **M2M OAuth Clients** tab.
2. Click **Create new > M2M OAuth Client**, name it, and save.
3. Open it, copy its **Client ID** and **Client Secret**, and configure your client with those plus the MCP Server URL.

See [M2M OAuth Clients](/carto-user-manual/developers/managing-credentials/m2m-oauth-clients.md) for details.

## Troubleshooting

* **"Callback URL mismatch"** — the redirect URL isn't registered on your SPA client, or doesn't match exactly. Recheck [step 3](#3-register-the-callback-url-back-in-carto).
* **"Unknown client"** — the Client ID doesn't resolve. Create a fresh SPA OAuth client and use its ID.
* **"Dynamic client registration is disabled"** — the client tried to register itself automatically. Choose the **Manual** / **User-Defined OAuth Client** option and enter your values by hand.
* **No tools after connecting** — confirm you connected over OAuth (not a token), and that any published Workflows have synced.
* **Permission errors** — the token inherits the signed-in user's permissions. Make sure that user can access the relevant connections and Workflows.

For token-based connections instead, see [Connecting with API Access Tokens](/carto-for-agents/mcp-server/connecting-with-api-tokens.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-for-agents/mcp-server/connecting-with-oauth.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.