MCP server

sn-mcp makes the platform agent-consumable: any MCP client (Claude Code, Claude Desktop, Cursor, Codex, VS Code, or your own agent) gets routing, dangerous-goods compliance, geocoding, matrix, elevation, optimisation, along-route search, day planning, reachability, place verification, map correction, integration feedback, local geometry and map-styling tools (fifty-two in total) with full JSON Schemas and structured outputs.

There are two ways in: connect to the hosted endpoint (nothing to install), or run the server yourself against a self-hosted deployment. Both are covered below.

Connect your agent (hosted, no install)

The hosted MCP server speaks streamable HTTP at:

https://mcp.mapmap.ai/mcp

Status, honestly: the endpoint is live and open for evaluation: no key needed to connect, fair use applies (rate limited per client IP; over the limit you get 429 with Retry-After). Every tool below is registered on the hosted endpoint, and the routing, geocoding, optimisation, place and local-geometry tools all answer there today.

You can also bill metered calls to your own gateway key: present your snk_ key as Authorization: Bearer snk_… on this endpoint and every metered call you make meters and bills to that key rather than to ours. That is how an agent pays its own way over MCP; connecting without a key still works for evaluation under fair use. See Authentication and billing below for exactly what is billed and what is free.

Presenting your own snk_ key also unlocks style publishes (create_style, set_palette, set_layer_paint) on this endpoint, because you are spending your own credential rather than ours. Without a key, publishes are still refused here: publishing has to be signed with a gateway key, and an open endpoint would otherwise have to sign it with ours. You can also publish by running the server yourself with your own STUDIO_API_KEY (below), or by calling POST /styles on the gateway with your snk_ key. Style reads stay open here, exactly as the gateway serves them. For the same capabilities over plain REST, call the REST API with your snk_ key.

Pick your client:

Claude Code

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

Claude Desktop / claude.ai: Settings, then Connectors, then Add custom connector, and paste:

https://mcp.mapmap.ai/mcp

Once added it also works from Claude in Slack and on mobile. This is the route for the hosted server; claude_desktop_config.json is for running a local process over stdio, which is further down this page.

Cursor: .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "mapmap": { "url": "https://mcp.mapmap.ai/mcp" }
  }
}

Codex: ~/.codex/config.toml:

[mcp_servers.mapmap]
url = "https://mcp.mapmap.ai/mcp"

VS Code (Copilot agent mode): .vscode/mcp.json:

{
  "servers": {
    "mapmap": { "type": "http", "url": "https://mcp.mapmap.ai/mcp" }
  }
}

Windsurf: ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mapmap": { "serverUrl": "https://mcp.mapmap.ai/mcp" }
  }
}

From code: the Claude API's MCP connector takes the URL directly:

{
  "mcp_servers": [
    { "type": "url", "url": "https://mcp.mapmap.ai/mcp", "name": "mapmap" }
  ]
}

Any other MCP client that supports streamable HTTP works the same way: give it the URL, no command, no environment variables.

Agent skills (knowledge, not tools)

The MCP server gives an agent live tools; agent skills teach it how to build with MapMap: truck and ADR routing patterns, web SDK integration, migrating from Mapbox, self-host operations. They install into Claude Code, Cursor, Codex and compatible agents:

npx skills add Mapmapai/mapmap-agent-skills            # all skills
npx skills add Mapmapai/mapmap-agent-skills --list     # see what's inside

Each of the eleven skills is listed and explained on the Agent skills page.

Comparing agent surfaces

An MCP server is easy to announce and harder to compare, so here is the measurement rather than the claim. Every figure below was read on 3 September 2026 from the repository or page linked beside it, the same way the optimisation limits are sourced. Restate the date if you quote this; these numbers move.

Two honest caveats on reading that table. Tool count is not capability: ours is higher partly because ten of the forty-seven are local geometry helpers that make no network call, and because dangerous-goods, clearance, fuel, charging and EV planning are separate products here rather than absent there. And NextBillion's server exposes place tools we do not match one for one, including static_map_image and postcode_lookup. The differences worth acting on are the keyless lane and the hosted transport, because they decide whether an agent can reach the tools at all without a procurement step.

If you are moving an integration across, the endpoint and parameter mapping is on Migrating from NextBillion.ai, and the commercial side is on the comparison page.

Resources and prompts

Beyond tools, the server publishes seven MCP resources and two prompts. The resources:

The first two are the deployment's own llms.txt and openapi.json. mapmap://guide/routing-mode is the only dynamic one: it reports which backend each network-calling tool on this server process is using right now, gateway-preferred or direct-backend fallback, and why. The ADR, clearance and skills entries are static reference documents. The last, ui://mapmap/route-map-v1.html (MIME type text/html;profile=mcp-app), is not a document to read but the route tool's output template: an HTML page that draws the returned geometry on the MapMap basemap with the distance and duration the tool reported, for clients that render MCP app UIs. It renders the tool's own structured content and calls nothing itself.

The two prompts are plan_truck_route (geocode → route with ADR costing → explain what the profile changed) and restyle_map_to_brand (the restrained brand-to-palette method, wired to the style tools). Connecting the server therefore delivers the knowledge layer as well as the tools: a client can read the orientation and the skills index without a single web request.

Two of those resources are static arguments rather than reference tables, and they are worth reading before an agent reports either kind of answer to a person. mapmap://guide/adr-tunnel-codes is what an ADR-costed route does and does not prove. mapmap://guide/clearance is the same job for check_clearance_on_route: why an unchanged truck route is not a clearance, why a surveyed measurement is not a signed height, and why ground the survey did not cover is reported as not surveyed rather than as clear. They share a sentence on purpose, and it is the sentence both products turn on. Full prose: measured clearance on a route.

Run it yourself

Everything below is for running sn-mcp against your own deployment: it is a thin front that needs the routing engine and (optionally) the geocoder, the VROOM optimisation solver and the gateway's style API reachable over HTTP. If you don't have one yet, start with Self-hosting.

Tools

Local geometry (no network, no quota)

Every tool above reaches a backend. These do not: they are pure computation over the coordinates you supply, so they work offline, cost nothing to serve, are never rate limited or metered, and keep answering when a backend is unavailable. They exist so an agent reasoning about space can stay in one tool surface instead of leaving it to do arithmetic.

All measurement is geodesic on the WGS84 ellipsoid, not a spherical approximation, so results agree with the datum the rest of the platform uses.

Upstream failures and invalid inputs come back as MCP tool errors with actionable messages, so agents can self-correct. In the tool inputs, a coordinate is a named {lat, lon} object (preferred, because it cannot be read the wrong way round) or a GeoJSON [lon, lat] array, longitude first, the same order every polygon field on the server takes. Answers always write coordinates back as {lat, lon} objects. Distances are metres and durations seconds throughout; see Conventions.

Environment variables

Each upstream is configured by one variable. All are optional at startup; a tool whose upstream is missing answers with an error naming the variable to set.

check_adr_tunnel and list_style_layers are fully local and need nothing.

Install

Status, honestly: the sn-mcp binary is not on a package registry yet. You build it from the source distribution (source access on request) or run it from the self-host distro's Docker image.

From source (Rust toolchain required):

cargo build --release -p sn-mcp
# binary at target/release/sn-mcp; copy it to /usr/local/bin/sn-mcp

As a container (from the distro):

docker build -f distro/Dockerfile --target mcp -t mapmap/mcp .

# stdio, for a desktop MCP client; -i keeps stdin open for the protocol
docker run -i --rm \
  -e VALHALLA_URL=http://valhalla:8002 \
  -e PHOTON_URL=http://photon:2322 \
  mapmap/mcp --transport stdio

(Point the container at your services' network; with the self-host distro, attach it to the compose network.)

Connect over stdio (local process)

Local process (stdio) only. This is for a sn-mcp binary running on the same machine, typically against your own self-host stack. To reach the hosted server at https://mcp.mapmap.ai/mcp from Claude Desktop, use Settings, Connectors, Add custom connector, as above.

Claude Desktop, add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mapmap": {
      "command": "/usr/local/bin/sn-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "VALHALLA_URL": "http://localhost:8002",
        "VROOM_URL": "http://localhost:3000",
        "PHOTON_URL": "http://localhost:2322",
        "STUDIO_URL": "http://localhost:8080",
        "STUDIO_API_KEY": "snk_..."
      }
    }
  }
}

Claude Code:

claude mcp add mapmap \
  --env VALHALLA_URL=http://localhost:8002 \
  --env VROOM_URL=http://localhost:3000 \
  --env PHOTON_URL=http://localhost:2322 \
  --env STUDIO_URL=http://localhost:8080 \
  --env STUDIO_API_KEY=snk_... \
  -- /usr/local/bin/sn-mcp --transport stdio

(The server key, mapmap here, is your choice.) Set only the variables for the tools you want; the server starts either way and logs a stderr warning for each missing upstream.

Connect over HTTP (remote agents)

The self-host distro runs the server with the mcp compose profile (default port 8200, endpoint path /mcp):

cd distro
docker compose --profile mcp up -d

Out of the box the compose service sets only VALHALLA_URL and PHOTON_URL. To enable optimise_routes, uncomment the vroom sidecar service and the service's VROOM_URL line; to enable the style tools, uncomment STUDIO_URL and STUDIO_API_KEY (comments in the compose file mark all three).

Then point your client at it:

{
  "mcpServers": {
    "mapmap": {
      "type": "http",
      "url": "http://your-host:8200/mcp"
    }
  }
}

Or with Claude Code:

claude mcp add --transport http mapmap http://your-host:8200/mcp

Example: a dimensioned truck route

A route call with a hazmat lorry profile:

{
  "origin": { "lat": 51.5074, "lon": -0.1278 },
  "destination": { "lat": 53.4808, "lon": -2.2426 },
  "costing": "truck",
  "truck": {
    "height_m": 4.0,
    "gross_weight_t": 40,
    "hazmat": true,
    "tunnel_code": "C"
  }
}

Structured result (truncated):

{
  "distance_m": 335412.0,
  "duration_s": 15102.0,
  "summary": "M1, M6",
  "maneuvers": [
    {
      "instruction": "Drive northwest on Whitehall.",
      "distance_m": 254.0,
      "duration_s": 41.0
    }
  ],
  "geometry_polyline6": "}vd~zAxwl@...",
  "applied_adr": {
    "hazmat": true,
    "tunnel_code": "C",
    "forbidden_tunnel_categories": ["C", "D", "E"],
    "costing_options": { "truck": { "height": 4.0, "...": "..." } }
  }
}

applied_adr shows exactly which ADR costing was merged into the request, so an agent can explain why a route avoids a tunnel.

Authentication and billing

Two different keys do two different jobs, and it helps to keep them apart:

• SN_MCP_AUTH_TOKEN is a self-hosted server's door key. Set it and every HTTP request must carry Authorization: Bearer <token> or get a 401. It gates access to the server; it is not a billing credential and never reaches the gateway.
• A gateway key (snk_…) is a caller's billing credential. Present it and every metered call you make is metered and billed to that key.

Bill metered calls to your own key

On the streamable-HTTP transport, present your gateway key as an ordinary bearer header:

Authorization: Bearer snk_your_key

The server reads that header per request and routes every metered call in the tool invocation through the MapMap gateway on your key, so the usage meters and bills to you rather than to the operator's shared key. This is what lets an agent pay per call on the hosted endpoint. It also works on a self-hosted HTTP server that is pointed at a gateway.

Only a bearer token with the snk_ prefix is treated as a billing key. An operator's SN_MCP_AUTH_TOKEN, or any other token, is not mistaken for one: the call then runs as an anonymous caller on the operator's key instead. So if you expect to be billed, check that the token you send actually begins snk_.

Set it in your client the same way you set the URL. Claude Code:

claude mcp add --transport http mapmap https://mcp.mapmap.ai/mcp \
  --header "Authorization: Bearer snk_your_key"

Any streamable-HTTP client that lets you set request headers works the same way:

{
  "mcpServers": {
    "mapmap": {
      "type": "http",
      "url": "https://mcp.mapmap.ai/mcp",
      "headers": { "Authorization": "Bearer snk_your_key" }
    }
  }
}

What is billed, and what is free

• Metered to your key are the tools that reach the MapMap gateway: route, geocode, reverse_geocode, matrix, reachable_area, optimise_routes, order_stops, cluster, replan_routes, submit_optimise_job, search_along_route, cheapest_fuel_along_route, weather_along_route, nearby_stops, next_departures, cheapest_charging_along_route, plan_ev_route, plan_errands, nearby_places, plan_day, elevation, and the itinerary feasibility pass in verify_places, plus the style publishes below. get_job is not metered: reading a job you submitted is free, deliberately, so polling is never something to ration. Each draws down that key's allowance and is priced exactly as the same capability over the REST API; see Pricing, and x402 payments for what happens once a key is past its allowance (the 402-versus-429 distinction is the same as on the gateway).
• Style publishes (create_style, set_palette, set_layer_paint) are metered publishes. A caller presenting their own snk_ key may publish with it on any transport, including an untrusted HTTP one, because they are spending their own credential rather than the operator's.
• Never metered, no key needed: the local-geometry tools (geo_*), validate_geodata, check_adr_tunnel, list_style_layers, check_style_contrast, and style reads (get_style). They are pure local computation or public reads, so they answer on any transport, with or without a key.

One nuance for self-hosting: the routing, matrix, geocoding and optimisation tools are metered only when the deployment reaches them through the gateway (as the hosted endpoint does, and as a self-host does once GATEWAY_URL and a key are set). A self-host wired directly to the engines (VALHALLA_URL, VROOM_URL, PHOTON_URL) with no gateway key calls them straight, and those calls are not API-key metered.

With no caller key

• Anonymous over HTTP dispatches unchanged on the operator's server. On the hosted endpoint that is the fair-use evaluation lane (rate limited per client IP, 429 with Retry-After over the limit), and style publishes are refused, because the server will not spend its own operator credential on an anonymous caller's behalf: hosted style ids are enumerable through the gateway's public GET /styles.
• Over stdio there are no per-request headers, so there is no caller key to read. You own the process, and calls use whatever key it was started with (GATEWAY_API_KEY, STUDIO_API_KEY), exactly as before.

Self-hosted HTTP server hardening

• The HTTP /mcp endpoint is unauthenticated unless you set SN_MCP_AUTH_TOKEN, in which case requests must carry Authorization: Bearer <token> or get a 401 (a caller may also carry their own snk_ billing key; the two do not conflict). It binds 127.0.0.1:8200 by default; pass --listen to widen that deliberately (the container image does, since a published port cannot reach a loopback bind). Anyone who can reach the port can call every keyless tool, so still run it inside your trust boundary, restrict it by network policy or add auth at your reverse proxy, and terminate TLS there exactly as for the gateway.
• In production pass --allowed-host (repeatable) so Host-header validation defends against DNS rebinding; when omitted, validation is off and the server warns at startup.

Troubleshooting

The server starts even with no upstreams configured, and tells you on stderr what won't work (stdout stays clean for the MCP protocol):

• VALHALLA_URL is not set: route, matrix, elevation, optimise_routes, search_along_route, plan_day and reachable_area will answer with errors
• VROOM_URL is not set: optimise_routes (and plan_day optimisation) will answer with errors
• PHOTON_URL is not set: geocode, verify_places and search_along_route will answer with errors
• STUDIO_URL is not set: the hosted style tools (get_style, create_style, set_palette, set_layer_paint) will answer with errors
• STUDIO_API_KEY is not set: style publishes (create_style, set_palette, set_layer_paint) will answer with errors; style reads still work
• SN_MAP_ISSUES_DIR is not set: report_map_issue will answer with errors
• neither GATEWAY_URL+GATEWAY_API_KEY nor SN_RETROS_DIR is set: submit_integration_retro will answer with errors
• SN_RETROS_DIR is not set: a retro the gateway cannot take (unreachable, rate-limited, key rejected) has nowhere to fall back to and is lost

The same guidance surfaces at call time: an unconfigured tool returns an MCP tool error naming the exact variable to set.

Next steps

• Self-hosting: run the deployment these tools talk to
• Route optimisation: the VRP problem model behind optimise_routes
• Conventions: units, coordinate order, ADR tunnel codes, error envelope
• API reference: the same capabilities over REST