# MCP Tools Reference This reference provides detailed information about all available MCP tools in CARTO's MCP Server that you can use to interact with your geospatial data from agentic platforms. Each tool entry includes a description, required parameters, and a practical example showing how natural language requests translate into tool usage.
Tool typeTool
Data management
Visualization
Workflows
*** ### `list_connections` **Description** Lists all available data warehouse connections for the account. Returns connection names, provider types, and IDs. **Example:** An agent asked *"What data do I have access to?"* would call `list_connections` to get a list: ``` [ { "name": "carto_dw", "provider": "bigquery" }, { "name": "my_snowflake", "provider": "snowflake" } ] ``` **Input properties:** *No parameters* **Output:** A JSON array of connection objects, each containing the connection name, provider type, and ID.
Response example ``` { "status": 200, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "carto_dw", "provider_id": "bigquery", "privacy": "shared", "carto_dw": true, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-06-20T14:22:00.000Z" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "my_snowflake", "provider_id": "snowflake", "privacy": "shared", "carto_dw": false, "created_at": "2024-03-10T08:00:00.000Z", "updated_at": "2024-03-10T08:00:00.000Z" } ] } ```
**Example** *"What data do I have access to?"* The agent calls `list_connections` with no parameters and returns a summary of available connections: ``` list_connections() ``` *** ### `list_resources` **Description** Browses the contents of a data warehouse connection hierarchically. Returns databases, schemas, tables, and views at the requested level. The hierarchy varies by provider: * **BigQuery:** connection > project > dataset > table/view * **Snowflake:** connection > database > schema > table/view * **Databricks:** connection > catalog > schema > table/view * **PostgreSQL / Redshift:** connection > database > schema > table/view Call with no `fqn` to see the top level, then pass an `fqn` to drill into a specific database or schema. Use `maxDepth=2` to expand one level deeper in a single call (e.g., see schemas AND their tables). **Input properties** | Parameter | Type | Required | Description | | ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `connection_name` | string | Yes | Name of the connection (from `list_connections`). | | `fqn` | string | No | Fully qualified name to browse. Omit for top level. Examples: `"my_database"`, `"my_database.my_schema"`. | | `maxDepth` | number | No | How many levels deep to expand (1=current level only, 2=include children, 3=include grandchildren). Default: 1, max: 3. | | `maxItems` | number | No | Maximum total items to return across all levels. Default: 30, max: 500. | **Output** A JSON object with a hierarchical structure of resources at the requested level. Each resource includes its name, fully qualified name, type (`database`, `schema`, `table`, or `view`), and any children if expanded.
Response example ``` { "status": 200, "data": { "provider": "bigquery", "type": "connection", "children": [ { "id": "my_project", "name": "my_project", "type": "database", "children": [ { "id": "my_project.retail_data", "name": "retail_data", "type": "schema", "children": [ { "id": "my_project.retail_data.stores", "name": "stores", "type": "table" }, { "id": "my_project.retail_data.sales_regions", "name": "sales_regions", "type": "table" } ], "childCount": 2, "childrenTruncated": false } ], "childCount": 5, "childrenTruncated": true } ], "returnedItems": 8, "maxItemsApplied": 30, "truncated": false, "rootChildrenTruncated": false, "totalRootChildren": 1 } } ```
**Example** *"What tables are in the retail\_data dataset?"* The agent first discovered the `carto_dw` connection via `list_connections`, then drills into a specific dataset: ``` // First call: list top-level projects list_resources({ connection_name: "carto_dw" }) // Second call: drill into a dataset and expand tables list_resources({ connection_name: "carto_dw", fqn: "my_project.retail_data", maxDepth: 2 }) ``` *** ### `search_resources` **Description** Searches for tables and views by name across a data warehouse connection. Returns a flat, ranked list of matches (exact match first, then prefix, then contains). Use this instead of `list_resources` when you know part of the table name but not where it lives. For faster results, pass a `scopeFqn` to narrow the search to a specific database or schema. Without a scope, multi-database providers (Snowflake, BigQuery, Databricks) search the first 10 databases/datasets alphabetically. The response includes `searchedContainers`/`totalContainers` so you know if the search was partial. **Input properties** | Parameter | Type | Required | Description | | ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `connection_name` | string | Yes | Name of the connection (from `list_connections`). | | `query` | string | Yes | Search string to match against table/view names (case-insensitive). | | `type` | string | No | Filter results to only `"table"` or only `"view"`. | | `limit` | number | No | Max results to return (1–100). Default: 20. | | `scopeFqn` | string | No | Narrow search to a specific database, schema, or dataset. Makes the search much faster. Examples: `"my_database"`, `"my_database.my_schema"`. | **Output** A JSON object containing a flat array of matching resources. Results are ranked by match quality (exact, then prefix, then contains). The `searchedContainers` and `totalContainers` fields indicate whether the search covered all databases/datasets or was partial.
Response example ``` { "status": 200, "data": { "provider": "bigquery", "results": [ { "id": "my_project.retail_data.stores", "name": "stores", "type": "table", "database": "my_project", "schema": "retail_data", "fqn": "my_project.retail_data.stores", "_links": { "resources": "/connections/carto_dw/resources/my_project.retail_data.stores" } }, { "id": "my_project.geo_data.stores_backup", "name": "stores_backup", "type": "table", "database": "my_project", "schema": "geo_data", "fqn": "my_project.geo_data.stores_backup", "_links": { "resources": "/connections/carto_dw/resources/my_project.geo_data.stores_backup" } } ], "returnedResults": 2, "truncated": false, "query": "stores", "scopeFqn": "my_project.retail_data", "searchedContainers": 1, "totalContainers": 1 } } ```
**Example** *"Do we have any table with store locations?"* The agent searches across the connection for tables matching "stores": ``` search_resources({ connection_name: "carto_dw", query: "stores", scopeFqn: "my_project.retail_data" }) ``` *** ### `view_map` {% hint style="warning" %} Note that the `view_map` tool is currently an **experimental prototype** and may change significantly as we develop it further. {% endhint %} **Description** Displays a table from a CARTO connection in an interactive map directly in the chat interface. The map viewer includes: * Pan, zoom, and tilt controls. * Column-based styling with automatic color ramps (sequential for numeric data, categorical for text) with deterministic color palettes (for now!). * An expandable data table with search and sort * Hover tooltips showing the styled column value
**Input properties** | Parameter | Type | Required | Description | | ---------------- | ------ | -------- | ------------------------------------------------------------ | | `connectionName` | string | Yes | CARTO connection name (e.g., `"carto_dw"`) | | `tableName` | string | Yes | Fully qualified table name (e.g., `"project.dataset.table"`) | **Output:** In MCP hosts that support [MCP Apps](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/apps) (e.g., Claude.ai, ChatGPT), an interactive map widget is rendered directly in the chat. In hosts that do not support MCP Apps, the tool returns a text confirmation:
Response structure ``` { "content": [ { "type": "text", "text": "Displaying CARTO table \"my_project.retail_data.stores\" from connection \"carto_dw\" on map" } ] } ```
{% hint style="info" %} `view_map` is enabled by default and renders as an embedded interactive widget in MCP hosts that support [MCP Apps](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/apps) (e.g., Claude.ai). In hosts that do not support MCP Apps, the tool returns a text confirmation instead. {% endhint %} **Example** *"Show me our store locations on a map"* The agent displays the stores table on an interactive map: ``` view_carto_map({ connectionName: "carto_dw", tableName: "my_project.retail_data.stores" }) ``` *** ### `async_workflow_job_get_status` **Description** Gets the status of an async workflow job. Use this after calling an async workflow tool that returns a job ID (`externalId`). Poll this tool until the job status is `success` or `error`. **Input properties** | Parameter | Type | Required | Description | | ---------------- | ------ | -------- | ---------------------------------------------------------------------------------- | | `jobId` | string | Yes | The ID of the async workflow job (the `externalId` returned by the workflow tool). | | `connectionName` | string | Yes | The name of the connection used by the workflow. | **Output** A JSON object containing the job status and metadata. Possible `status` values: `pending`, `running`, `success`, `failure`, `cancelled`.
Response example ``` { "status": 200, "data": { "jobId": "abc-123", "connectionName": "carto_dw", "providerId": "bigquery", "status": "running", "error": null, "createdAt": "2024-06-20T14:30:00.000Z" } } ```
**Example** After launching an async workflow that returned `jobId: "abc-123"`: ``` async_workflow_job_get_status({ jobId: "abc-123", connectionName: "carto_dw" }) ``` *** ### `async_workflow_job_get_results` **Description** Retrieves the results of an async workflow job after it has completed with `success` status. Call this only after `async_workflow_job_get_status` confirms the job is done. **Input properties** | Parameter | Type | Required | Description | | ------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- | | `jobId` | string | Yes | The ID of the async workflow job. | | `providerId` | string | Yes | The data warehouse provider. One of: `bigquery`, `snowflake`, `databricks`, `postgres`, `redshift`, `oracle`. | | `connectionName` | string | Yes | The name of the connection used by the workflow. | | `workflowOutputTableName` | string | Yes | The fully qualified name of the workflow output table. | **Output** A JSON object containing the query results from the workflow output table. The `rows` array contains the actual data, and `schema` describes the column types.
Response structure ``` { "status": 200, "data": { "rows": [ { "store_id": 1, "name": "Madrid Centro", "trade_area_geom": "POLYGON((-3.71 40.41, ...))", "drive_time_min": 10 }, { "store_id": 2, "name": "Madrid Norte", "trade_area_geom": "POLYGON((-3.69 40.48, ...))", "drive_time_min": 10 } ], "schema": [ { "name": "store_id", "type": "INT64" }, { "name": "name", "type": "STRING" }, { "name": "trade_area_geom", "type": "GEOGRAPHY" }, { "name": "drive_time_min", "type": "INT64" } ] } } ```
**Example** After confirming the job completed successfully: ``` async_workflow_job_get_results({ jobId: "abc-123", providerId: "bigquery", connectionName: "carto_dw", workflowOutputTableName: "my_project.results.trade_areas" }) ```