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 (thirty-four 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_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

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

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 ten skills is listed and explained on the Agent skills page.

Resources and prompts

Beyond tools, the server publishes MCP resources (the deployment's own llms.txt and openapi.json, the ADR tunnel-code reference, the measured-clearance reference and the agent-skills index) and two prompts: 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.

Status, honestly: resources and prompts ship with the next server release; they are in the source now and appear on the hosted endpoint at its next deploy. Tools are unaffected either way.

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, coordinates are named {lat, lon} objects (unambiguous, unlike positional arrays); 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)

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, search_along_route, cheapest_fuel_along_route, nearby_places, plan_day, elevation, and the itinerary feasibility pass in verify_places, plus the style publishes below. 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