carto-preview-builder-map
Renders a lightweight inline preview of an existing saved CARTO Builder map via the CARTO MCP server's
tool. The user references the map (by URL, ID, or name); the agent locates it and loads it inline.
Tool contract. This skill consumes the
and
tools exposed by the CARTO MCP server. The tools' input shapes and access-control rules (the user must own, be shared on, or have public access to the map) are documented in the tool's own MCP description — read it via the MCP host's tool-inspector or by calling
. This skill stays focused on routing, name → ID resolution, and setting expectations on the lightweight preview; it does NOT duplicate the tool's spec.
This skill assumes the
CARTO MCP server is attached (the
and
tools are in your tool list) AND the
host supports MCP Apps (Claude.ai, Claude Desktop, ChatGPT). If either is missing, see "Step 1 — detect what's available" below.
Step 1 — detect what's available
| Check | How |
|---|
| and are callable | Both tool names appear in your tool list. |
| Host renders MCP Apps | Hosts that DO: Claude.ai, Claude Desktop, ChatGPT. Hosts that DON'T (Gemini CLI, Codex CLI, plain MCP Inspector, current MCPJam) execute the tool but only show a text confirmation — no map widget. |
| Setup | What to do |
|---|
| Tools present + host renders | Proceed normally. |
| Tools present + host doesn't render | Tell the user the host can't render maps inline; suggest opening the Builder URL directly. |
| Tools not present | The MCP server isn't attached. Tell the user; don't try to reconstruct the saved map from scratch. |
Resolution rules (URL / ID / name)
| User input | What to do |
|---|
Builder URL https://<workspace>.app.carto.com/builder/<mapId>
| Extract from the URL; call load_builder_map({ mapId })
|
| Bare UUID | Call load_builder_map({ mapId })
|
| Name / topic ("the retail-stores map", "my last week's accidents analysis") | Call list_maps({ search: "<topic>" })
|
For name-based lookup, use
if the user said "my map". Default sort is
— most recently edited first.
Match handling (after )
| Result | Action |
|---|
| 1 match | load_builder_map({ mapId: <id> })
|
| >1 matches | List names + dates + thumbnails. Ask the user to pick. Don't guess. |
| 0 matches | Tell the user no saved map matches. Offer () as an ad-hoc alternative for the same data. |
Set expectations on the preview (always)
The preview is lightweight:
- ✓ Layers, basemap, viewport, popups, legend — exactly as configured in Builder.
- ✗ Widgets, SQL parameters, map description, AI agent configuration, and other Builder-only features are NOT included.
After loading, tell the user: "Loaded [name] as a lightweight preview. Widgets, SQL parameters, and the map description aren't included — click 'Open in Builder' in the rendered widget for the full experience." Set this expectation BEFORE the user asks why the preview looks different from the live Builder map.
Post-CLI-creation preview workflow
When the user creates a permanent map via
(from
carto-create-builder-maps
), the response is a
+ Builder URL. With the MCP server attached, preview inline immediately:
# carto maps create returned { mapId: "abc-123", ... }
load_builder_map({ mapId: "abc-123" })
This is the fastest authoring loop: edit, save via CLI, preview inline via MCP, repeat. Especially useful for styling iterations.
Caveat: still the lightweight preview. If the user is debugging widgets or SQL parameters, they need the full Builder experience.
When to pick a different skill
- Ad-hoc visualization, no saved map exists → ().
- Authoring / editing a permanent map →
carto-create-builder-maps
- Building a from-scratch deck.gl app → .
Anti-patterns to avoid
- Reconstructing a saved map via instead of . If the user references an existing map, ALWAYS try + first. Re-rendering loses fidelity (saved layers, popups, legend) AND it's slower.
- Skipping when the user references a map by name. Don't guess the ID. Search first.
- Promising widgets, SQL parameters, or map description in the preview. They're not rendered. Set expectations upfront.
- Picking the most-recent match silently when returns multiple. Surface the choices and let the user pick.