Skip to content

Built for AI agents, not retrofitted.

An agent gets a working API key in one call, with no card, no CAPTCHA and no sales call, then routes trucks, checks dangerous-goods compliance and publishes map styles by pure API.

agent session · mcp.mapmap.ai · real responses, replayed
1Discover

Orientation, endpoints and prices in machine-readable form. No scraping.

GET mapmap.ai/llms.txt
GET mapmap.ai/pricing.json
2Get a key

Card-free, live immediately. Email verification upgrades the same key to 50,000 calls a month.

POST api.mapmap.ai/v1/keys
{ "email": "…", "accept_tos": true }
→ 201 { "key": "snk_…", "calls": 1000 }
3Route

Connect the MCP server, or call the REST API directly: same engine, same errors.

claude mcp add --transport http \
  mapmap https://mcp.mapmap.ai/mcp

Full flow, error envelope and quotas: /docs/quickstart

Key issuance takes an optional source tag naming where the request came from, and the recipes in /docs/agents set it themselves. The first tag an identity carries is the one kept: it is never overwritten, and it changes nothing about the key.

One URL. Every client.

The hosted MCP server speaks streamable HTTP at https://mcp.mapmap.ai/mcp: no install, no key to connect, fair use. Pick your client:

Claude Code
claude mcp add --transport http mapmap \
  https://mcp.mapmap.ai/mcp
Cursor
{ "mcpServers": {
    "mapmap": { "url": "https://mcp.mapmap.ai/mcp" } } }
Install in Cursor →
Claude Desktop
{ "mcpServers": {
    "mapmap": { "type": "http", "url": "https://mcp.mapmap.ai/mcp" } } }
Codex
[mcp_servers.mapmap]
url = "https://mcp.mapmap.ai/mcp"
VS Code
{ "servers": {
    "mapmap": { "type": "http", "url": "https://mcp.mapmap.ai/mcp" } } }
Install in VS Code →
Windsurf
{ "mcpServers": {
    "mapmap": { "serverUrl": "https://mcp.mapmap.ai/mcp" } } }
From code
"mcp_servers": [
  { "type": "url", "url": "https://mcp.mapmap.ai/mcp", "name": "mapmap" } ]

Copy-pasteable config for every client, plus self-host: /docs/mcp. Client names and marks are trademarks of their respective owners, shown to indicate compatibility.

MCP server

Fifty-two tools, six jobs.

Every one of them, grouped by what it talks to. Full JSON Schemas and structured outputs, so a model calls them correctly on the first try. Tool errors name the exact problem, so agents self-correct.

01 · Route & comply

The differentiator: truck routing where ADR dangerous-goods tunnel codes and vehicle dimensions shape the route itself, not a post-filter.

route

Turn-by-turn for auto or truck; the truck profile merges dimensional and ADR costing. Distance, duration, manoeuvres, geometry.

check_adr_tunnel

Pure ADR 8.6.4 tunnel-entry decision: decision, reason, explanation. No network, answers instantly.

optimise_routes

Multi-vehicle, multi-stop optimisation with truck and ADR constraints, fed by our own matrices.

order_stops

One vehicle, one run: put the errands in the best visiting order, with arrival offsets. Truck costing keeps the order restriction-aware.

cheapest_fuel_along_route

Cheapest fuel on the way, ranked by real engine-measured detour time and price per litre, from live statutory open-data feeds.

weather_along_route

The forecast for the hour you reach each point of a route: rain, snow, gusts and visibility, with one plain summary. Advisory, never a routing guarantee.

nearby_stops

England bus and coach stops near a point, with their stop codes and the lines that call there. Display data, never a journey plan.

next_departures

Timetabled departures at a bus stop, each with any bus seen on that line heading in. Timetable times: MapMap does not predict arrivals.

cheapest_charging_along_route

EV charge points on the way from operator-published feeds, with engine-measured detours, connector and minimum-kW filters, and a coverage statement so an empty result is never read as “no chargers here”.

plan_ev_route

A whole electric journey with its charge stops: physics consumption over the real legs, the charging curve integrated, and an honest infeasible answer rather than an invented plan.

plan_errands

A chain of errands ordered against a hard arrival time: real shops from the map, engine-computed times, and when it will not all fit, the errand that breaks it and the shorter chain that does. Planned before setting off, never at the wheel.

check_clearance_on_route

Overhead clearance along a truck route measured against surveyed point-cloud geometry: pass, fail, indeterminate or no verdict, with the limiting point and its uncertainty bound.

cluster

Split a day too large for one optimisation into balanced clusters to optimise one at a time. Straight-line by design, and it says so.

replan_routes

Re-plan a fleet mid-shift: the original problem plus what has been served, cancelled or added. We hold no dispatch state, so nothing is assumed about the day.

submit_optimise_job / get_job

The asynchronous lane for problems too large for one request, and the free poll that reads the result back.

© OpenStreetMap contributors

02 · Search & measure

Ground an agent in the map: place search, many-to-many travel costs, and a check on the places a model claims are real.

geocode

Forward geocoding: name, label, position and address parts per candidate.

reverse_geocode

Coordinates to the nearest places: addresses, POIs and localities, nearest first with distance in metres. The inverse of geocode. Pass a heading and results come back described from where the user is standing rather than as coordinates.

nearby_places

Nearest-first search around a point, by category (cafes, fuel, EV charging, parking) or by name and brand, with real distances. Pass heading_deg and every result is phrased egocentrically, “ahead and slightly to your right, about 80 metres”, with a signed relative bearing; add fov_deg to keep only what is in front of the user. Without a heading it falls back to cardinals, so a client with no compass still gets something it can read aloud.

places_in_view

What is over there, and whether you could see it. Give it a position and a bearing and it returns the places in that cone, each with its distance, how far off dead ahead it sits, and an honest verdict: clear, occluded with the obstruction named, or unknown when nothing could be checked. Visibility is modelled from the terrain and OpenStreetMap building heights, never observed, and the response says so.

route_observations

What a journey passes, in sentences ready to read aloud: the named rivers it crosses, the road it runs on and for how far, the settlements it goes through, the landscapes it enters and how high the road climbs. None of it is in a route object, so it is computed by intersecting the route geometry with the basemap and the terrain model. The silence budget is the design, and the coverage block separates “nothing there” from “nothing read”.

heritage_narration

Three to five short lines an hour about the ground the car is on, each at the point it belongs. Every sentence was written from a public-domain plaque inscription and reviewed by a person before it shipped, so no model runs while anybody is driving. It covers one corridor on purpose, and every other route answers with no lines and a census of what was out of reach.

verify_places

Check places and itineraries a model mentioned against the map before you act on them. Each claim comes back verified, contradicted or unverified, never a boolean, and a missing match is unverified rather than a denial. Pass a locality with every claim: a bare name is searched worldwide, so a short name can verify against a same-named place in another country.

matrix

Many-to-many travel-time and distance matrix; null cells mark unreachable pairs.

search_along_route

Stops from your own places dataset along a route, ranked by honest detour cost: real added driving time, measured by the engine.

reachable_area

Isochrone rings: where you can reach inside a chosen time budget on foot, by bike or by car.

plan_day

Turn a list of stops into a navigable multi-stop route with per-stop arrival times; optionally optimises the order.

elevation

Terrain height for a list of points, or a resampled profile along a route. Null wherever the terrain set has no coverage, never a guess.

match_trace

Snap a recorded GPS trace to the roads it actually travelled, under the costing it was travelled with, so a walk is not matched onto the carriageway.

list_place_categories

The canonical category tokens and their colloquial aliases. Read it before guessing: an unknown token matches nothing and returns empty rather than erroring.

03 · Style maps

Agents publish real hosted map styles: recolour a palette, override one layer's paint, ship an immutable new version.

list_style_layers

Everything a theme can restyle: palette slots, layer ids, source-layers. Local, instant.

get_style

A hosted style's theme document and compiled style URL. Public read.

create_style / set_palette / set_layer_paint

Build and restyle hosted maps; every publish is a new immutable version.

check_style_contrast

Audit a style against WCAG 2.1 across both palette variants. Advisory: it names the slots to fix, and never blocks a publish.

04 · Compute locally

Eleven tools that never leave the process: no network call, no quota, never metered or rate limited, and they keep answering when a backend is down. Measurement is geodesic on the WGS84 ellipsoid, not a spherical approximation, so it agrees with the rest of the platform.

geo_distance

Metres between two coordinates, as the crow flies. Not a driving distance: use route or matrix for that.

geo_bearing

Initial bearing between two coordinates, degrees clockwise from true north.

geo_destination

The coordinate reached by travelling a distance on a bearing. The inverse of geo_distance plus geo_bearing.

geo_point_in_polygon

Is this coordinate inside the zone? Delivery areas, catchments, clean-air and congestion zones. On the boundary counts as outside.

geo_bbox

The axis-aligned box enclosing a set of coordinates, for fitting a map view to a set of stops.

geo_centroid

The centroid of a set of coordinates: pick a depot, centre a map.

geo_length

Total length of a polyline in metres. Measures the line you supply, not a driven route.

geo_area

Area in square metres inside a ring. Always positive, so winding direction cannot change the answer.

geo_simplify

Douglas-Peucker simplification. The tolerance is in degrees, not metres, and endpoints are always kept.

geo_nearest_point_on_line

The closest position on a polyline to a coordinate, plus the distance to it. Answers “how far is this address from the route?”

validate_geodata

Does a dataset's declared CRS actually describe its own coordinates? Catches swapped axes, degrees labelled as metres and a mislabelled projection before anything is drawn. A check, never a reprojection.

05 · Report back

Three tools that point back rather than out at the map: an agent that finds the map wrong, or the integration painful, can say so in a structured form rather than filing a ticket a human has to translate, and it can read its own spend before deciding to carry on.

report_map_issue

Queue a map correction for review: location, category, evidence. Never an automatic OpenStreetMap edit.

submit_integration_retro

Send a structured end-of-integration retro so the friction you hit gets fixed. Only the named fields travel, never your conversation, prompts or code, and only with the developer's approval.

get_usage

What this key has spent, per day and per endpoint, against its quota and prepaid balance. Reading it is free, so an agent can decide mid-task whether to keep going.

06 · Camera-verified incidents

Off unless a deployment arms them. What a traffic camera saw and a vision model confirmed, and an operator's own short closures: both expire on their own and rank below official closures.

camera_incidents

Incidents in force near a point, in a box or along a route, each with the clip it was verified on, the confidence and when it lifts. An empty answer is no camera-verified incident, never a clear road.

set_temporary_closure

An operator's short-lived closure or speed on named roads, admin only, and only after a person approves that exact closure.

Agents pay per call.

Past the free tier, the gateway answers 402 in the x402 wire format, quoting the exact price of the call. Prepaid credit settles it, and so does on-chain settlement via the X-PAYMENT header: live on the hosted gateway since 20 July 2026, in USDC on Base and Solana, through a facilitator. A self-hosted deployment switches it on in its own configuration. Fails closed: routing is served only after a valid payment. Never a surprise bill.

402 x402 body: a way to pay429 honour Retry-AfterRFC 9457 stable problem types/openapi.json the contract
How machine payments work →
the 402 payment shape
HTTP/1.1 402 Payment Required

{
  "x402Version": 1,
  "error": "monthly free quota exhausted",
  "accepts": [ /* PaymentRequirements */ ],
  "instructions": "pay per call, or top up credit"
}
Data rights

Agents are the customer, not a ToS violation.

Every response an agent pays for is its to keep: cache it, store it, index it, train on it, forever. MapMap meters the live service, not your memory of it. The incumbents take the opposite view: Google caps most caching at 30 days and bans AI training outright; Mapbox's default terms allow queries only in response to a human.

One honest boundary: content derived from OpenStreetMap stays under ODbL, so credit © OpenStreetMap contributors when you republish, and share-alike applies to public derivative databases. That is OSM's licence, not ours to waive. Everything else is yours.

the cache-forever contract
GET /.well-known/agent-terms.json

{
  "rights": {
    "cache":  "unlimited",
    "store":  "unlimited",
    "index":  true,
    "train":  true,
    "redistribute": "with ODbL/OSM
      attribution where applicable"
  },
  "commitments": [
    "We will never add a caching time
     limit, a storage ban, an indexing
     ban or a training ban ..." ]
}
What an agent may doMapMapGoogle Maps PlatformMapbox
Automated and bulk queries✓ Yes. Agents are the customerNo scraping, pre-fetching or bulk downloads (§3.2.3(a))Human queries only; no bulk or automated queries (§1.9)
Cache responses✓ ForeverBanned except narrow allowances, e.g. geocoded lat/lng for 30 days (§3.2.3(b), SST §6.3)Banned by default; on-device tile cache capped at 30 days (§1.9, §2.8.1)
Store results long-term✓ Yes, unlimited“pre-fetch, index, store, reshare, or rehost” all banned (§3.2.3(a))“export, download, cache or store” banned; navigation results never storable (§1.9, §2.10.1)
Build a derivative dataset✓ Yes, under ODbL attribution and share-alike where OSM-derivedNo creating content from Google Maps Content (§3.2.3(c))No general POI or geocode database; no substitute service (§1.5, §2.7.1)
Train AI models✓ YesBanned: no train, test, validate or fine-tune (§3.2.3(c)(vii))Banned, narrow data-product exceptions by separate order (§1.5(ii))
Pay without a human✓ Yes: x402, USDC on Base and SolanaNo: human billing account and cardNo: human billing account and card
MCP server✓ 52 hosted tools, keyless connectDocs-assist MCP only (experimental); data access stays under the same termsYes, token required; the same product terms apply to results

Summaries of the cited clauses, not legal advice; read the originals. Sources: Google Maps Platform Terms of Service §3.2.3 (last modified 23 June 2026) and Maps Service Specific Terms (SST) §6.3 (last modified 10 June 2026); Mapbox Product Terms §§1.5, 1.9, 2.7, 2.8.1, 2.10.1 (last updated 21 July 2026). All checked 26 July 2026. If the linked documents have changed since, they win.

Skills: teach your agent to build with MapMap.

The MCP server is live tools; the skills are the know-how, installed into the same agents. See all eleven →

truck & ADR patternsweb SDK integrationbranded map designfleet VRPoffline mapsmigrate from Mapbox or Googlemachine paymentsself-host ops
npx skills add Mapmapai/mapmap-agent-skills

Wire an agent up in minutes.

Start at the discovery files, issue a key in one call, connect the MCP server.