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

For CLI-based agents like Gemini CLI, see Connecting with API Access Tokens.

Prerequisites

• A CARTO organization with access to the Developers section.

• At least one Workflow exposed as an MCP Tool. See 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.

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

The callback URL must match exactly what the AI platform expects. Do not use the default callback URLs — each platform requires a specific URL.

MCP Jam requires two callback URLs. Enter both URLs separated by commas in the Allowed Callback URLs field.

Step 2: Connect from your AI platform

Use the MCP Server URL (from the overview page), 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

• ChatGPT — Using remote MCP servers

• MCP Inspector on GitHub

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.

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.

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

• No tools appear after connecting: Ensure your Workflows are published as MCP Tools and have been synced. See 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.