carto-basics

CARTO is reachable through two parallel access paths, and most agent setups use one or both:

CARTO MCP Server — the primary path for inline, in-conversation work in chat-based agent hosts (Claude.ai, Claude Desktop, ChatGPT, and other MCP clients). When attached, it exposes a broad consolidated tool surface: exploring data, creating and editing Builder maps, authoring and running Workflows, running SQL, import/export, and org admin. Renders maps inline on hosts that support MCP Apps, and dynamically registers the user's published Workflows as MCP tools. This covers most interactive requests.
CARTO CLI (@carto/carto-cli) — the path for scripting, CI/CD, headless contexts, bulk and cross-org operations, deeper administration and auditing (e.g. SQL over usage logs), and the fullest command surface. Used by many platform skills in this catalog, and the fallback whenever the MCP server isn't attached.

Use this skill before any other CARTO skill — it covers how to detect and route between the two access paths, plus CLI installation, authentication, profiles, and the global flags the CLI-driven skills assume.

When to use this skill

Setting up the CLI for the first time on a new machine.
The user reports authentication errors (auth status failures, expired tokens).
The user wants to switch between organizations or environments.
A downstream skill needs --profile, --json, --token, or --base-url and you don't yet know how those work.

Preflight — run before any CLI operation

Skills that drive the CLI assume a working, authenticated carto CLI. If the attached MCP server already covers the request (exploring data, creating maps, running Workflows in a chat host), you don't need the CLI at all — route through MCP. Run the checks below before your first CLI call, and re-run them at the start of each task — ephemeral sandboxes (e.g. Claude Code Cowork tasks) wipe the CLI between tasks. An attached MCP server, by contrast, persists at the account level (see below).