Skip to main content
Glama
Mapbox MCP Server

Mapbox MCP Server

Official
by mapbox

Mapbox Map

render_map_tool
Read-onlyIdempotent

Render a live, interactive Mapbox GL JS map to view locations, routes, or datasets, and merge multiple data sources onto one map with optional traffic, satellite imagery, and styling.

Instructions

Display a live, interactive Mapbox GL JS map. Use this when someone wants to see a location, route, or dataset on a map. In ChatGPT Desktop the map stays open next to the chat and provides its own tools (redraw_map, which takes the same arguments as this tool, search_map, add_places, move_map, read_map): use them to change that map, because another call to this tool opens a second map. Preferred usage: any other Mapbox tool returns a mapboxRender.ref URI in its structuredContent — pass that ref via payload_refs: ["..."]. You can pass multiple refs to merge several datasets (e.g. a search result + a route) onto one map. Inline layers/markers/legend fields are also supported for hand-composed payloads from raw GeoJSON. For a hand-composed POI marker (e.g. built from category_search_tool/search_and_geocode_tool/place_details_tool output), set markers[].id to the place's mapbox_id — this gets it the same auto-enriching results carousel (popularity score and photo) that a payload_refs-based search result gets automatically, with no extra tool calls. To restyle the base map itself (e.g. "make the water red", switch to night lighting, hide POI labels) pass baseMapConfig. To switch to satellite imagery, pass baseStyle: "standard-satellite" (defaults to "standard"). To show live traffic congestion on the roads in view, pass showTraffic: true. The map also has Satellite and Traffic buttons users can toggle themselves. Every call redraws the map from scratch: only the traffic and satellite settings carry over from the previous call. So to restyle an already-drawn map or toggle traffic without losing its content, re-pass the same payload_refs/layers alongside baseMapConfig/baseStyle/showTraffic rather than sending them alone. After rendering places, don't list them again in your reply: the map's cards already show each name, category, price level, distance and hours. Answer the question or add what the cards leave out (like the phone number or address) instead.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "render_map_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
cameraNoInitial camera position. If omitted, the map auto-fits to the union of all data.
layersNoInline layers to add to the map. Use this only when composing a payload from raw GeoJSON; for tool results, pass payload_refs instead.
legendNoInline legend rows. Use only for hand-composed payloads.
markersNoInline point markers (start/end, numbered visits, POI pins, etc.). Use only for hand-composed payloads. For POI markers, set `id` to the place's mapbox_id to get an auto-enriching results carousel card (see markerSchema's `id` field) instead of just a pin.
summaryNoShort header chip shown in the top-left of the map (e.g. "Route: 12.4 mi, 23 min"). Overrides any summary in payload_refs.
baseStyleNoWhich Mapbox-owned base style to load; defaults to "standard". "standard-satellite" is the same Standard style family rendered over global satellite imagery instead of a vector basemap — same config-property system and bottom/middle/top slots apply, but it has no theme and no flat-color overrides like colorWater/colorBuildings (there's no vector surface to recolor). See https://docs.mapbox.com/map-styles/reference/standard-satellite/ for its supported baseMapConfig properties.
showTrafficNoShow live traffic congestion (light/moderate/heavy/severe) on every road in view, from Mapbox Traffic. Use when the user asks to see traffic or congestion in an area. Works on both base styles. Left out, the map keeps whatever the user picked with its Traffic button.
payload_refsNoArray of map-payload URIs returned by other Mapbox tools in their structuredContent.mapboxRender.ref field. Pass one ref to render a single tool result; pass multiple to merge several datasets onto one map (e.g. an isochrone + a route).
baseMapConfigNoRestyles the Standard base map itself via Mapbox's config-property system (map.setConfigProperty) — e.g. { "colorWater": "#ff0000" } to turn the water red, or { "lightPreset": "night" } for night lighting. Only the currently-documented Standard properties are typed above; unrecognized keys still pass through in case Mapbox ships new ones. Has no effect if the base style isn't Standard.

Output Schema

NameRequiredDescriptionDefault
summaryNo
renderedYesAlways true when the call succeeded.
layer_countYes
mapboxRenderNo
marker_countYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.18.1

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond readOnlyHint/idempotentHint by disclosing a non-obvious stateful behavior: every call redraws from scratch and only traffic/satellite settings persist, with the workaround (re-pass the same payload_refs/layers alongside the style flags) spelled out. It also describes automatic enrichment (results carousel, popularity, photo, hours) via `markers[].id`, and gives an output-side instruction to avoid duplicating card data in the reply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the preferred payload_refs pattern, then progressively detailed. It is long and slightly repetitive about the carousel enrichment (repeated in both the marker paragraph and the prose), but nearly every sentence carries operational information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, nested-object tool with lives next to the chat, the definition covers the multi-call workflow, the ref-merging idiom, style/traffic persistence, and the reply behavior after rendering. With an output schema present it correctly avoids explaining return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning the schema can't: payload_refs is for merging multiple tool results onto one map, `markers[].id` triggers an enriching carousel with no extra tool calls, `baseMapConfig` is the restyle path, and `baseStyle: "standard-satellite"` is the satellite switch. It also explains the interaction constraint that these flags don't survive alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Display a live, interactive Mapbox GL JS map') and immediately separates itself from static_map_image_tool by stressing 'live, interactive'. It also names the in-map tools (redraw_map, search_map, add_places, move_map, read_map) so the agent knows this is the map host rather than a one-shot renderer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: other Mapbox tools return a `mapboxRender.ref` and it should be passed via `payload_refs`; inline `layers`/`markers`/`legend` are reserved for hand-composed raw GeoJSON. It states a concrete when-NOT ('another call to this tool opens a second map') and names the alternative (redraw_map) to use instead, which is the exact failure mode an agent would otherwise hit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.