cartodb carto-connect-datawarehouse
CARTO runs spatial analytics in the user's own data warehouse. A connection is the bridge between CARTO and that warehouse: it carries credentials, target project/database scoping, and sometimes a service account or PAT. Most other CARTO operations (querying, importing, building maps, running workflows) require an existing connection.
| Task | MCP | CLI (fallback) |
|---|---|---|
| List / inspect connections | explore_data (list_connections on any session; get_connection is OAuth-only) |
carto connections list / get |
| Create / update a connection | manage_connections (create, update) — OAuth session only |
carto connections create / update |
| Delete a connection | delete (kind=connection) — OAuth session only |
carto connections delete |
Access-path routing. With the MCP server attached, list over
explore_data(list_connections); create/update overmanage_connections; delete overdelete. On a token session onlylist_connectionsis available —get_connectionand the write tools (manage_connections,delete) need OAuth, so fall back to thecarto connectionsCLI. Also use the CLI when the server isn't attached or for scripted setups. The engine-choice guidance and pitfalls below apply on either path. Detection signals:carto-basics/references/access-paths.md.
When to use this skill
- The user wants to connect a new warehouse to CARTO.
- The user is debugging a connection (auth failures, missing tables, permission errors).
- A downstream skill needs a connection name and you don't yet know which engine the user has.
- The user is rotating credentials or moving from one project/database to another.
Use carto-explore-datawarehouse once a connection exists and you want to inspect what's inside it.
Quick lifecycle (CLI)
carto connections list --json # what's already connected? (--all, --search "prod")
carto connections get <id> # detailed view of one connection
carto connections create # interactive create
carto connections update <id> # rotate credentials, change scoping
carto connections delete <id> # remove (irreversible)
List/inspect are non-destructive — run them freely before deciding what to do. If the user already has a connection, don't push a new one — use the existing one.
Choosing an engine
| Engine | When to choose it | Reference |
|---|---|---|
| BigQuery | Google Cloud users; CARTO's flagship integration; rich GIS functions native. | references/bigquery.md |
| Snowflake | Snowflake-shop customers; geospatial via SQL functions and native types. | references/snowflake.md |
| Redshift | AWS-shop customers on Redshift Serverless or RA3 clusters. | references/redshift.md |
| Postgres | Self-hosted or RDS Postgres with PostGIS; common for small/medium deployments. | references/postgres.md |
| Databricks | Lakehouse / Unity Catalog users; SQL Warehouses for interactive workloads. | references/databricks.md |
| Oracle | Oracle Database with Spatial; on-prem or OCI / Autonomous Database. | references/oracle.md |
Common pitfalls
- Auth-mode mismatch: BigQuery supports OAuth (interactive) and service-account JSON (CI). Pick one consistently per environment; mixing the two breaks shared connections.
- Region vs project: Some engines need both an account/project and a region (Snowflake, Redshift). Skipping the region typically yields "endpoint not found" rather than a permissions error.
- Default database/schema scoping: CARTO writes tilesets, named sources, and analytics output back into the warehouse. Confirm which dataset/schema CARTO may write to before creating the connection.
- Permissions for describe and table reads come from the credential CARTO holds, not the user's CARTO role. A CARTO Admin with a low-privilege service account still sees "permission denied" from the warehouse.
What this skill doesn't cover
- Browsing tables/schemas of an existing connection —
carto-explore-datawarehouse. - Running SQL against the warehouse —
carto-query-datawarehouse. - Importing files into the warehouse —
carto-import-export-data.