carto-render-inline-map

Renders an ad-hoc interactive map inline in the chat via the CARTO MCP server's

view_map

tool. The agent emits a

@deck.gl/json

declarative spec; the renderer handles credentials, basemap, and tooltips. The user sees the map without leaving the chat.

Legend required after every render. The

view_map

renderer does NOT show an auto-legend. After invoking

view_map

, render a legend through the host's widget surface (e.g.,

show_widget

in Claude.ai / Claude Desktop) — that is the ONLY visual transport that works. Chat-message HTML is escaped by every major host's renderer and appears as raw text — DO NOT emit HTML in your chat reply. If the host has no widget tool, fall back to a plain-text legend (markdown bullets with emoji color squares per bucket, hex codes in parentheses). The full HTML template, style rules, and per-helper variants (

colorBins

swatches,

colorContinuous

gradient bar,

colorCategories

per-category, raster ternary-bucket + nodata) live in the

view_map

tool description's LEGEND section. Applies to

view_map

ONLY;

load_builder_map

has its own Builder-native legend.

Tool contract. This skill consumes the

view_map

tool exposed by the CARTO MCP server. The tool's input shape (

deckglProps

), layer-source compatibility,

aggregationExp

requirements, and

@@=

expression-eval restrictions 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, cartography, and the agent's reply; it does NOT duplicate the tool's spec.

This skill assumes the CARTO MCP server is attached (the

view_map

tool is in your tool list) AND the host supports MCP Apps (interactive widgets — 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
`view_map` is callable	Tool name `view_map` is 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
Tool present + host renders	Proceed normally.
Tool present + host doesn't render	Tell the user the host can't render maps inline; suggest switching hosts or using `carto-create-builder-maps` (CLI) for a screenshot-based alternative.
Tool not present	The MCP server isn't attached. Tell the user; don't fall back to a generic visualization widget.

When to pick a different skill

Permanent / shareable map →
```
carto-create-builder-maps
```
(CLI).
```
view_map
```
specs aren't saved or shareable as URLs; they live in the chat.
Open an existing saved map by name/URL/ID →
```
carto-preview-builder-map
```
. That skill uses
```
load_builder_map
```
to render a saved Builder map inline.
Writing a TypeScript/JavaScript app from scratch →
```
carto-develop-app
```
. Different runtime (full deck.gl surface in JS), different cartography rules.

Discovery flow before composing the spec

```
list_connections
```
→ identify the right connection (often
```
carto_dw
```
).
```
search_resources
```
(by name) or
```
list_resources
```
(by FQN) to find the table.
Always call
get_column_stats
for any unfamiliar numeric column you'll bin on — quantiles, min, max, categories. Skipping this and hardcoding
```
colorBins
```
thresholds is the #1 styling failure mode.
Compose the
```
view_map
```
spec.

Composition essentials

For the full deck.gl declarative spec — layer-source compatibility,

aggregationExp

rules,

mapStyle

URLs,

@@function

shapes, expression-eval restrictions — read the

view_map

tool description directly. This skill stays focused on routing and cartographic decisions.

For cartographic decisions on the spec (palette, scale, basemap, stroke, drawing order, hierarchy, picking, anti-patterns, worked recipes), read

references/cartography.md

. Mandatory before composing any styled spec.

Anti-patterns to surface or self-correct

Falling back to a generic visualization widget when
view_map
is available. If the tool is in your list, use it.
view_map
for a saved map referenced by name. Switch to
```
carto-preview-builder-map
```
and call
```
list_maps
```
first.
Hardcoded
colorBins
domain values without
get_column_stats
. Always fetch real percentiles for unfamiliar columns.
Mixing tile schemes (e.g.,
```
vectorTableSource
```
→
```
HeatmapTileLayer
```
). Silent empty render. The
```
view_map
```
tool description has the full compatibility matrix.
Generic deck.gl layers (
```
ScatterplotLayer
```
,
```
HexagonLayer
```
,
```
GeoJsonLayer
```
, etc.). The MCP JSON converter only registers CARTO layers — anything else silently produces nothing.
Treating an inline preview as a saved/shareable map. It isn't. If the user wants to keep it, route to
```
carto-create-builder-maps
```
.

Post-CLI-creation preview pattern

When the user creates a permanent map via the CLI (

carto maps create

from

carto-create-builder-maps

), the response is a

mapId

+ Builder URL. The fastest way to verify the result inline is

load_builder_map

(in

carto-preview-builder-map

) — NOT a re-rendered

view_map

. Hand off to that skill rather than reconstructing the spec from scratch.

carto-render-inline-map

NPX Install

Tags

SKILL.md Content

carto-render-inline-map

Step 1 — detect what's available

When to pick a different skill

Discovery flow before composing the spec

Composition essentials

Anti-patterns to surface or self-correct

Post-CLI-creation preview pattern