Connecting with API Access Tokens

An API Access Token is the quickest way to connect an agent for read and discovery work — browsing connections, querying data, and searching the Data Observatory. It's also the only option on hosts that don't run an interactive OAuth flow (such as Oracle OCI). You create a token in CARTO Workspace, then pass it as an authorization header when registering the MCP Server in your agent.

A token session reaches a read-and-discovery subset of the tools — it can't create or edit maps, author Workflows, or reach admin. For the full surface, use OAuth.

The token's Allowed APIs decide which tools appear — and the MCP Server scope alone unlocks only four. See What a token unlocks below before you create the token; the difference between four tools and fourteen is which data APIs you add.

Step 1: Create an API Access Token

The MCP Server requires authentication via an API Access Token:

1. In CARTO Workspace, create a new token.

2. In Allowed APIs, switch on the MCP Server scope — this admits the token to the server. Then add the data APIs the agent actually needs: SQL to query at all, Maps for table stats (describe), LDS for geocoding and routing, Imports/Exports to load and export data. See What a token unlocks — the MCP Server scope on its own reaches only four tools.

3. Under Grants, add at least one grant naming a connection.

4. Copy the token securely, using the copy button — you'll need it to connect the agent.

Get the SQL grant source right, or queries will fail. A grant is a {connection, source} pair, and what source must contain depends on the API:

• For the SQL API (execute_query), source must be the query text itself, or * for any query — not a table name. A table-scoped grant returns 403 for a SELECT against that table.

• For map and table reads, source is a fully-qualified table name.

For an agent that composes its own SQL, granting * is usually the practical choice.

What a token unlocks

Which tools a token session sees depends entirely on its Allowed APIs. The MCP Server scope is only the admission ticket — on its own it reaches four tools. Each additional data API adds more:

Allowed API	Tools it unlocks
MCP Server (alone)	explore_data (list connections, browse and search resources — not describe), search_data_observatory, validate_map, validate_workflow. Four tools.
+ SQL	execute_query and execute_async_query (the agent can't query at all without this), plus run_workflow status only — it can poll a run, but starting one and fetching results needs OAuth.
+ Maps	describe on explore_data — table and column statistics, which data-aware map styling depends on.
+ LDS	geocode, route, calculate_isolines, calculate_od_matrix.
+ Imports / Exports	import_data, export_data, transfer_data.

With SQL, Maps, LDS, Imports and Exports all enabled, a token reaches fourteen tools. Everything beyond that — creating and editing maps, authoring and running Workflows, connections, and admin — is OAuth only.

"Read-and-discovery" describes the shape, not a safety guarantee: execute_query and execute_async_query can run DDL/DML against the warehouse (the async tool covers writes). Scope the token's Grants to control what an agent can touch.

Step 2: Add the MCP Server to your agent

Use the MCP Server URL (from the overview page) and the API Access Token to register the server. The exact command varies by agent — most take a URL, a transport, and an Authorization: Bearer <token> header. For example, with Gemini CLI:

gemini mcp add carto \
  https://<region>.api.carto.com/mcp/<account_id> \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -t http

• Replace <region> and <account_id> with the values from your MCP Server URL (copy the full URL from Developers > Workflow API & MCP Server).

• -t http sets the transport protocol (Streamable HTTP).

• The Authorization header carries the API Access Token from Step 1.

After setup, the agent can browse your connections, inspect tables, run SQL, and search the Data Observatory in response to your questions — the exact set depends on the token's Allowed APIs (see What a token unlocks). Running a saved Workflow end to end needs OAuth.