# Connecting with OAuth

Some AI platforms — including Claude.ai, ChatGPT, and others — connect to MCP Servers using OAuth authentication. Instead of manually copying an API token, you log in through the platform's interface and are redirected to CARTO to authorize access.

This is an alternative to the [API Access Token method](https://docs.carto.com/carto-mcp-server/carto-mcp-server/connecting-with-api-tokens). OAuth is well suited for web-based AI platforms that handle the authentication flow natively, while API Access Tokens work better for CLI-based agents like Gemini CLI.

{% hint style="info" %}
For CLI-based agents like Gemini CLI, see [Connecting with API Access Tokens](https://docs.carto.com/carto-mcp-server/carto-mcp-server/connecting-with-api-tokens).
{% endhint %}

## Prerequisites

* A CARTO organization with access to the Developers section.
* At least one Workflow exposed as an MCP Tool. See [Workflows as MCP Tools](https://docs.carto.com/carto-user-manual/workflows/workflows-as-mcp-tools) for setup instructions.

## 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. "Claude.ai 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](https://docs.carto.com/carto-user-manual/developers/managing-credentials/spa-oauth-clients).

### Callback URLs by platform

| MCP Client    | Callback URL                                                                         |
| ------------- | ------------------------------------------------------------------------------------ |
| Claude.ai     | `https://claude.ai/api/mcp/auth_callback`                                            |
| 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="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](https://docs.carto.com/carto-mcp-server/carto-mcp-server/..#get-the-mcp-server-url)), **Client ID**, and **Client Secret** to set up the connection. The exact steps vary by platform — refer to each platform's own documentation for detailed instructions:

* [Claude.ai — How to connect remote MCP integrations](https://support.claude.com/en/articles/11175166-how-to-connect-remote-mcp-integrations-to-claude)
* [ChatGPT — Using remote MCP servers](https://platform.openai.com/docs/guides/tools-remote-mcp)
* [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.

{% 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 %}

## 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](https://docs.carto.com/carto-user-manual/workflows/workflows-as-mcp-tools).
* **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: 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:

```
GET https://docs.carto.com/carto-mcp-server/carto-mcp-server/connecting-with-oauth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.