carto-preview-builder-map

Renders a lightweight inline preview of an existing saved CARTO Builder map via the CARTO MCP server’s load_builder_map 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 load_builder_map and list_maps 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 tools/list. 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 load_builder_map and list_maps 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

Resolution rules (URL / ID / name)

For name-based lookup, use mine_only: true if the user said “my map”. Default sort is updated_at desc — most recently edited first.

Match handling (after list_maps)

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 carto maps create (from carto-create-builder-maps), the response is a mapId + 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 → carto-render-inline-map (view_map).
• Authoring / editing a permanent map → carto-create-builder-maps (CLI).
• Building a from-scratch deck.gl app → carto-develop-app.

Anti-patterns to avoid

• Reconstructing a saved map via view_map instead of load_builder_map. If the user references an existing map, ALWAYS try list_maps + load_builder_map first. Re-rendering loses fidelity (saved layers, popups, legend) AND it’s slower.
• Skipping list_maps 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 list_maps returns multiple. Surface the choices and let the user pick.