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.

No other caller is affected. 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​