Codex

Codex can work with CARTO through a remote MCP server, the CARTO Agent Skills, and the CARTO CLI.

• MCP — gives Codex access to CARTO tools.

• Agent Skills — gives Codex reusable CARTO-specific instructions and workflows.

• CARTO CLI — provides command-line access for scripting, automation, and administration.

Together, these let Codex use CARTO tools while following CARTO-specific patterns and workflows.

Before you start: Copy your MCP Server URL from CARTO Workspace under Workspace > Settings > MCP Server

MCP

Connect to the MCP Server

Add CARTO using the Codex CLI:

codex mcp add carto --url https://<region>.api.carto.com/mcp/<account_id>

Alternatively, add the server manually to ~/.codex/config.toml:

[mcp_servers.carto]url = "https://<region>.api.carto.com/mcp/<account_id>"bearer_token_env_var = "CARTO_TOKEN"  # optional; sent as Authorization: Bearer <value>

Replace <region> and <account_id> with the values from your CARTO MCP Server URL.

Authentication

For OAuth, which provides the full CARTO tool surface, start the browser-based login:

codex mcp login carto

For read-and-discovery access, set CARTO_TOKEN to a CARTO API Access Token:

export CARTO_TOKEN="<your-CARTO-token>"

The token is sent as:

Authorization: Bearer <value>

CARTO CLI

Codex runs in a terminal, so the CARTO CLI can be used alongside MCP and Agent Skills for scripting, automation, and administration.

Install the CLI:

npm install -g @carto/carto-cli

Authenticate:

carto auth login

The CLI is useful when a task is better suited to command-line operations, scripting, or CARTO administration than to an MCP tool call.

Agent Skills

CARTO Agent Skills complement MCP and the CLI. They provide CARTO-specific instructions and workflows that help Codex use both interfaces consistently and idiomatically.

Install the CARTO Agent Skills through the Codex plugin manifest. See Agent Skills → Installation for setup instructions.

MCP provides Codex with access to CARTO tools, while the CLI provides command-line capabilities. Skills provide the guidance for using them effectively.