Connecting with API Access Tokens

CLI-based agents such as Gemini CLI connect to the CARTO MCP Server using API Access Tokens. You create a token in CARTO Workspace, then pass it as an authorization header when registering the MCP Server in your agent.

For web-based AI platforms like Claude.ai that support OAuth, see Connecting with OAuth.

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 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, select the MCP Server permission scope.

3. Copy the token securely, as it will be required to connect the agent to the server.

Step 2: Add MCP Server to your agent

Use the MCP Server URL (from the overview page) and the API Access Token to register the server in your agent. For example, with Gemini CLI:

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

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

• -t http specifies the transport protocol.

• The Authorization header includes the API Access Token created in the previous step.

After this setup, the agent will be able to call the MCP Tools you created with Workflows and return geospatial results in response to questions.