Skip to main content

Maps for AI agents

maproll ships an MCP server, so an AI assistant can build a map from your data and hand back a URL you can embed.

{
"mcpServers": {
"maproll": {
"command": "npx",
"args": ["-y", "@maproll/mcp"]
}
}
}

That is the whole setup. No signup, no credentials — the server runs from npm on demand and talks to the same public render API as everything else in these docs. One optional key changes whose wordmark the map carries; see the wordmark below.

World choropleth of coffee consumption per capita, built through the maproll MCP server

Why a server rather than just the URL​

An assistant that can already make HTTP requests can already call api.maproll.io. What the server adds is the part it cannot guess:

  • The grammar. Nothing in a model's training says that region data packs as US:200:#ff0000, or that markers are lat,lon[:icon][:label][:position][:size]. The tools take structured arguments and write the URL themselves.
  • Coordinates. Models recall latitude and longitude badly, and a map renders a wrong marker exactly as confidently as a right one. find_places resolves them against real data.
  • The rendered result. Every map-making tool returns the PNG alongside the URL, so the assistant — and you — can see what was made.

What comes back​

Every tool that makes a map returns the same shape:

FieldWhat it is
svg_urlThe map. Embeddable, permanent, and the handle other tools accept.
png_urlThe same map as PNG.
editor_urlOpens the map in app.maproll.io, loaded and editable.
embedA ready <img> tag.
warningsNon-fatal problems, such as region ids the renderer did not recognise.

Alongside those fields, the rendered PNG comes back as an image content block, so a client that displays images shows the map without fetching anything.

There is no session. svg_url is the state — pass it to add_layers and you get a new URL back with the addition applied. That means a map can be built up over several turns, and any URL from any point in the conversation still renders. See working with existing maps.

The wordmark​

Every render the MCP server makes is tagged src=mcp. For that traffic, with no key present, the maproll wordmark is forced on — a logo=false passed through extra is ignored. So today, with no key, every map your assistant makes carries the wordmark.

A key changes that. Keys are minted in the editor at app.maproll.io and set as MAPROLL_API_KEY in the server's environment. The returned URLs then come back signed, logo defaults to off, and extra: { logo: false } is honoured — see Install.

The editor and plain URL embeds keep whatever they ask for, and the wordmark is off by default there. Attribution to OpenStreetMap stays on in every case — that is a licence obligation, not a branding choice.

Next​