Skip to main content

Mapbox Integration

Connect your Mapbox account to Revelry Ai to give the AI location tools in chat: find points of interest, turn addresses into coordinates and back, and calculate travel distances, times, and directions.

Mapbox is an organization-level integration. An admin adds a Mapbox access token once, and every member of your Revelry Ai organization can use the Mapbox tools in chat.

Prerequisites​

  • A Mapbox account and an access token (a free Mapbox account is enough to start)
  • Manage Integrations permission in Revelry Ai to connect or manage the integration
  • The Mapbox integration must be enabled for your organization

What You Can Do​

The tools are grouped into two toolsets you can turn on or off independently.

POI & Geocoding​

  • Search points of interest by name, by category (restaurant, coffee, gas station, hotel, hospital, parking, and so on), or both, optionally near a location and within a radius
  • Geocode an address or place name into coordinates, with the best match first
  • Reverse geocode coordinates into an address with its neighborhood, city, region, postcode, and country

Distance & Directions​

  • Calculate distance and travel time between two points along the road network
  • Get step-by-step directions between two points
  • Build a distance matrix of travel times and distances between every pair in a set of up to 25 locations (up to 10 when using live traffic)

Travel tools support four profiles: driving (the default), driving with live traffic, walking, and cycling. Distances come back in meters, kilometers, and miles; durations as readable times.

All Mapbox tools are read-only, so none of them go through the approval gate.

Connecting Mapbox​

  1. Go to the Integrations page (under My Organization in your account menu at the bottom of the left navigation)
  2. Switch to the Shared tab (Mapbox is an organization-level integration)
  3. Find Mapbox and click Connect MCP Tool
  4. Paste your Mapbox Access Token
  5. Click Save Configuration

Revelry Ai validates the token against Mapbox before saving it. If validation fails, the error message tells you why (an invalid token, missing permissions, or a rate limit).

Finding your access token​

  1. Sign in to Mapbox
  2. Open your Access tokens page
  3. Copy your default public token, or create a token for Revelry Ai

Any token that can call the Geocoding, Search, Directions, and Matrix APIs works. Mapbox usage from Revelry Ai counts against your Mapbox account's quotas.

Choosing toolsets​

Once connected, the Mapbox integration page shows a Toolsets section with two toggles, POI & Geocoding and Distance & Directions. Both are on by default. Turning one off removes its tools from chat without disconnecting the integration.

Using Mapbox in Chat​

Once connected, the AI can use Mapbox during chat when the integration is enabled:

  1. Start or continue a chat
  2. Make sure Mapbox is enabled in the Chat Tools menu (under Integrations)
  3. Ask location questions naturally

Example prompts:

  • "Find hardware stores within 5 miles of the Main Street job site"
  • "What are the coordinates of 1500 Poydras St, New Orleans?"
  • "How long is the drive from our office to the Baton Rouge site in morning traffic?"
  • "Give me directions from the warehouse to 400 Canal St"
  • "Build a travel time matrix between these six project addresses"

The AI calls the appropriate Mapbox tools, and you'll see tool execution cards showing what was retrieved. When you give addresses rather than coordinates, the AI geocodes them first. The same toggle is available in the skill builder, so skills can use Mapbox tools when they run.

Managing the Connection​

  1. Navigate to Integrations and open Mapbox on the Shared tab
  2. Click Manage Connection to replace the token or change toolsets
  3. Click Disconnect in the configuration dialog to remove the integration

Disconnecting deletes the stored token from Revelry Ai and disables the Mapbox tools for everyone in your organization. The token itself stays valid in your Mapbox account; delete it there if you no longer want it usable anywhere.

Troubleshooting​

The Mapbox card is missing. The integration may not be enabled for your organization. Contact your Revelry Ai team.

Saving fails with "invalid Mapbox access token". Check for copy and paste errors, and confirm the token has not been deleted or rotated in your Mapbox account.

Saving fails with "access denied". The token's scopes do not allow the Mapbox APIs the tools use. Create a token with the default public scopes.

Chat says the access token is invalid or revoked. The token was deleted or rotated in Mapbox. Open Manage Connection and save a new one.

Chat says "Mapbox API rate limit exceeded". Your Mapbox account hit its request limit. Wait the number of seconds shown and try again.

"Mapbox could not compute a route." There is no drivable, walkable, or cyclable route between the points for the chosen profile, or a point is too far from any road.

Next Steps​