> 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 lets AI clients connect to the CARTO MCP Server without manually managing tokens. There are two flavors: * **OAuth (U2M)**: user-to-machine. The user logs in through the client and is redirected to CARTO to authorize access. Best for interactive clients like Claude.ai, Claude Code, or ChatGPT. * **OAuth (M2M)**: machine-to-machine. The client authenticates with its own credentials and connects unattended, with no user login. For token-based connections instead, see [Connecting with API Access Tokens](/carto-for-agents/mcp-server/connecting-with-api-tokens.md). ## OAuth (U2M) OAuth (U2M) requires a user to authenticate with their CARTO credentials. Adding an MCP Server varies by client, so refer to your client's own documentation: * [Claude Code](https://code.claude.com/docs/en/mcp-quickstart) * [Claude.ai (web and desktop)](https://support.claude.com/en/articles/11175166-how-to-connect-remote-mcp-integrations-to-claude) * [ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta) (requires a paid plan and Developer Mode) {% hint style="info" %} If your organization signs in to CARTO through single sign-on (SSO), copy the **SSO login** URL from **Developers > Workflow API & MCP Server** instead of the standard one, so the interactive login goes through your identity provider. See [Using CARTO MCP Server](/carto-for-agents/mcp-server.md#using-carto-mcp-server). {% endhint %} On the CARTO side, how much setup you need depends on whether your client supports CIMD. ### Clients supported with CIMD **Claude.ai** and **Claude Code** support Client Identifier Metadata Document (CIMD) registration, so CARTO recognizes them automatically. **You do not need to create any OAuth client: no SPA client, no M2M client, nothing.** Just point the client at the URL and log in: 1. Copy the **MCP Server URL** from **Developers > Workflow API & MCP Server**. 2. Add it as a new MCP Server in your client (see the links above). 3. When the client connects, you are redirected to CARTO. Log in with your CARTO account to authorize access. That's it. The connection is ready to use. ### Other clients Other clients, including ChatGPT, MCP Inspector, and MCP Jam, do not support CIMD, so you must create a SPA OAuth client in CARTO and connect with its credentials. This requires a CARTO organization with access to the Developers section. #### Step 1: Create a SPA OAuth Client Navigate to **Developers > Credentials** in CARTO Workspace. Switch to the **SPA OAuth Clients** tab and click **Create new > SPA OAuth Client**. 1. Enter a descriptive **Name** (e.g. "ChatGPT MCP Connection"). 2. Uncheck **"Use default logout/callback URLs and origins"**. 3. In **Allowed Callback URLs**, enter the URL that matches your AI platform (see table below). 4. Click **Save changes**. 5. Copy the **Client ID** and **Client Secret**. You will need them in Step 2. For more details on SPA OAuth Client configuration, see [SPA OAuth Clients](/carto-user-manual/developers/managing-credentials/spa-oauth-clients.md). **Callback URLs by platform** | MCP Client | Callback URL | | ------------- | ------------------------------------------------------------------------------------ | | ChatGPT | `https://chatgpt.com/connector_platform_oauth_redirect` | | 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` | {% hint style="info" %} Claude.ai and Claude Code do not appear here because they use CIMD and skip this manual setup entirely. See [Clients supported with CIMD](#clients-supported-with-cimd). {% endhint %} {% hint style="warning" %} The callback URL must match exactly what the AI platform expects. Do not use the default callback URLs. Each platform requires a specific URL. {% endhint %} {% hint style="info" %} MCP Jam requires two callback URLs. Enter both URLs separated by commas in the Allowed Callback URLs field. {% endhint %} #### Step 2: Connect from your AI platform Use the **MCP Server URL** (from the [overview page](/carto-for-agents/mcp-server.md#using-carto-mcp-server)), **Client ID**, and **Client Secret** to set up the connection. The exact steps vary by platform, so refer to each platform's own documentation: * [ChatGPT: Developer Mode and full MCP connectors](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta) * [MCP Inspector on GitHub](https://github.com/modelcontextprotocol/inspector) In general, the process is: 1. Open the MCP or connectors settings in your AI platform. 2. Add a new MCP connection and enter the **MCP Server URL**. 3. Enter the **Client ID** and **Client Secret** from Step 1. 4. Complete the OAuth authorization when redirected to CARTO. 5. After authorization, your CARTO MCP Tools will be available in conversations. ### What you authorize During the authorization step, you grant the AI platform permission to use the CARTO MCP Server on your behalf: listing and running your published Workflows, browsing your data warehouse connections, locating your saved Builder maps, and rendering interactive visualizations. The OAuth token inherits the rest of your CARTO permissions: the connections, datasets, and maps your user account has access to. You can revoke the connection at any time from your CARTO Workspace under **Developers > Credentials > SPA OAuth Clients**, or from your AI platform's connector settings. {% hint style="warning" %} **Timeouts in web-based clients.** Web platforms typically enforce short request timeouts (around 10 seconds). Make sure your Workflows can complete within that window when using **Sync** mode. For longer-running processes, use **Async** mode and instruct the agent to use the available tools for polling execution status and fetching results when the job is finalized. {% endhint %} ## OAuth (M2M) OAuth (M2M) provides unattended access over OAuth using a machine-to-machine OAuth client, with no interactive user login. This requires a CARTO organization with access to the Developers section. 1. In CARTO Workspace, go to **Developers > Credentials** and switch to the **M2M OAuth Clients** tab. 2. Click **Create new > M2M OAuth Client**, enter a descriptive **Name**, and save. 3. Open the client with **View or edit credential** and copy its **Client ID** and **Client Secret**. 4. Configure your AI client with the **MCP Server URL** (from the [overview page](/carto-for-agents/mcp-server.md#using-carto-mcp-server)), **Client ID**, and **Client Secret**. The client exchanges these for an access token and connects with no user login. For more details on M2M OAuth Client configuration, see [M2M OAuth Clients](/carto-user-manual/developers/managing-credentials/m2m-oauth-clients.md). ## Troubleshooting * **Authentication fails or redirects to the wrong URL:** Verify that the Allowed Callback URL in your SPA OAuth Client matches the platform exactly. See the [callback URL table](#callback-urls-by-platform) above. * **No tools appear after connecting:** Ensure your Workflows are published as MCP Tools and have been synced. See [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools.md). * **Permission errors after authenticating:** The OAuth token inherits the permissions of the CARTO user who authenticated. Ensure that user has access to the relevant Workflows and data connections. --- # 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=&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.