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.

Looking for setup steps for a specific platform? See Connect your platform. This page explains the shared OAuth mechanics behind those guides.

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 for the exact clicks.

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.

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

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.

Callback URLs for common clients

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.

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

Troubleshooting

• "Callback URL mismatch" — the redirect URL isn't registered on your SPA client, or doesn't match exactly. Recheck step 3.

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