Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Mapbox

Scalekit connector
Open markdown

The Mapbox connector lets your AI agent act in each user's Mapbox account. Each user connects their own Mapbox API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 20 tools.

Tools
20
What they doRead · write · destructive
20 · 0 · 020 read0 write0 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the Mapbox connection

    In AgentKit > Connections, create a Mapbox connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'mapbox'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Mapbox:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'mapbox_geocode_forward_structured',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Mapbox credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • mapbox_dataset_feature_getGet one GeoJSON feature from a Mapbox dataset by its ID.Read-only

    Get Dataset Feature

    Get one GeoJSON feature from a Mapbox dataset by its ID. Returns the feature with id, geometry and properties. Use mapbox_dataset_feature_get when you know the feature ID. Use mapbox_dataset_features_list to browse. Needs a token with the datasets:read scope.

    Inputs

    dataset_idstringrequired
    ID of the dataset, from mapbox_datasets_list. Example: cjvf1msb3060i2vp6bq9m7t6l.
    feature_idstringrequired
    ID of the feature, from mapbox_dataset_features_list. Example: f6d9.
    usernamestringrequired
    The Mapbox username of the account that owns the datasets, shown in the Mapbox console. Example: mapbox-user.
  • mapbox_dataset_features_listList the GeoJSON features stored in a Mapbox dataset.Read-only

    List Dataset Features

    List the GeoJSON features stored in a Mapbox dataset. Returns a GeoJSON FeatureCollection; each feature has id, geometry and properties. Use mapbox_dataset_features_list to read a dataset's data. Use mapbox_dataset_feature_get for one feature by ID. Needs a token with the datasets:read scope. To get the next page, pass the id of the last feature as start, and stop when no features come back.

    Inputs

    dataset_idstringrequired
    ID of the dataset, from mapbox_datasets_list. Example: cjvf1msb3060i2vp6bq9m7t6l.
    usernamestringrequired
    The Mapbox username of the account that owns the datasets, shown in the Mapbox console. Example: mapbox-user.
    limitinteger
    Maximum number of features, from 1 to 1000. Defaults to 1000. Example: 100.
    startstring
    ID of the last feature on the previous page, to list the features after it. Example: f6d9.
  • mapbox_dataset_getGet the metadata of one Mapbox dataset.Read-only

    Get Dataset

    Get the metadata of one Mapbox dataset. Returns id, name, description, owner, created, modified, bounds, features (the count) and size in bytes. Use mapbox_dataset_get to inspect one dataset. Use mapbox_dataset_features_list to read its features. Needs a token with the datasets:read scope.

    Inputs

    dataset_idstringrequired
    ID of the dataset, from mapbox_datasets_list. Example: cjvf1msb3060i2vp6bq9m7t6l.
    usernamestringrequired
    The Mapbox username of the account that owns the datasets, shown in the Mapbox console. Example: mapbox-user.
  • mapbox_datasets_listList the datasets in a Mapbox account.Read-only

    List Datasets

    List the datasets in a Mapbox account. Returns an array of datasets, each with id, name, description, owner, created, modified, bounds, feature count and size. Use mapbox_datasets_list to find a dataset_id. Use mapbox_dataset_get for one dataset and mapbox_dataset_features_list for its features. Needs a token with the datasets:list scope. Mapbox can return fewer than limit before the end; to get the next page, pass the id of the last dataset as start, and stop when a page comes back empty.

    Inputs

    usernamestringrequired
    The Mapbox username of the account that owns the datasets, shown in the Mapbox console. Example: mapbox-user.
    limitinteger
    Maximum number of datasets to return. Example: 20.
    sortbystring
    Sort order: modified (most recently changed first) or created (oldest first). Example: modified.one of modifiedcreated
    startstring
    ID of the last dataset on the previous page, to list the datasets after it. Example: cjvf1msb3060i2vp6bq9m7t6l.
  • mapbox_directions_getGet a route between 2 to 25 points for driving, driving with traffic, walking or cycling from the Mapbox Directions API.Read-only

    Get Directions

    Get a route between 2 to 25 points for driving, driving with traffic, walking or cycling from the Mapbox Directions API. Returns routes, each with distance in meters, duration in seconds, geometry and legs (with turn-by-turn steps when steps is true), plus the snapped waypoints and a code such as Ok or NoRoute. Use mapbox_directions_get to route through points in the given order. Use mapbox_optimized_trip_get to find the best visiting order, mapbox_matrix_get for travel times between many points, and mapbox_map_matching_get to snap a recorded GPS trace. Get coordinates from mapbox_geocode_forward or mapbox_search_forward when you only have addresses.

    Inputs

    coordinatesstringrequired
    The points to route through, in order, as 2 to 25 longitude,latitude pairs separated by semicolons. Example: -122.42,37.78;-122.45,37.91.
    profilestringrequired
    Routing profile: driving-traffic (car, with live and historic traffic), driving (car), walking or cycling. Sent as mapbox/<profile>. Example: driving.one of driving-trafficdrivingwalkingcycling
    alternativesboolean
    Set true to also return up to two alternative routes when they exist. Defaults to false. Example: true.
    annotationsstring
    Extra per-segment data to return, comma-separated: distance, duration, speed, congestion, congestion_numeric, maxspeed, closure. Needs overview set to full. Congestion and closure are only available for driving-traffic. Example: distance,duration.
    approachesstring
    Side of the road to arrive from at each waypoint, semicolon-separated: unrestricted (default) or curb. Give one value per waypoint; leave a position empty to skip it. The first value is not used, so start the list with a semicolon. Example: ;curb.
    arrive_bystring
    Desired arrival time, in the same ISO 8601 formats as depart_at. Only for the driving profile. Example: 2026-12-01T09:00.
    bearingsstring
    Direction of travel at each coordinate, semicolon-separated, each as angle,deviation in degrees clockwise from true north (deviation 45 or 90 is typical). Leave a position empty to skip it. Example: 60,45;;45,45.
    continue_straightboolean
    Set true to keep going in the same direction after an intermediate waypoint, or false to allow a U-turn. Defaults to true for driving and false for walking and cycling. Example: false.
    depart_atstring
    Departure time, in ISO 8601 format YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mm:ss±hh:mm or YYYY-MM-DDThh:mm (local time at the first coordinate). Only for driving and driving-traffic. Do not combine with arrive_by. Example: 2026-12-01T08:30.
    excludestring
    Road types to avoid, comma-separated: motorway, toll, ferry, unpaved, cash_only_tolls, tunnel, country_border, state_border (most only for driving and driving-traffic). Avoidance is best effort. Example: toll,ferry.
    geometriesstring
    Format of returned route geometry: geojson (a GeoJSON LineString), polyline (precision 5, the default) or polyline6 (precision 6). Use geojson to read coordinates directly. Example: geojson.one of geojsonpolylinepolyline6
    languagestring
    Language of turn-by-turn instruction text, such as en, de or es. Defaults to en. Only used with steps set to true. Example: de.
    max_heightnumber
    Vehicle height in meters, 0 to 10, to avoid roads with lower limits. Driving profiles only. Example: 3.5.
    max_weightnumber
    Vehicle weight in metric tons, 0 to 100, to avoid roads with lower limits. Driving profiles only. Example: 7.5.
    max_widthnumber
    Vehicle width in meters, 0 to 10, to avoid narrower roads. Driving profiles only. Example: 2.5.
    overviewstring
    Detail of the overview geometry: full, simplified (the default) or false for none. Example: full.one of fullsimplifiedfalse
    radiusesstring
    Maximum distance in meters each coordinate may move to snap to the road network, one value per coordinate separated by semicolons; leave a position empty to use the default. Values: any number greater than 0 or unlimited. Example: 50;;100.
    stepsboolean
    Set true to return turn-by-turn steps and instructions. Defaults to false. Example: true.
    waypoint_namesstring
    Names for the waypoints, semicolon-separated, used in arrival instructions; the first is the origin. Up to 500 characters in total. Only used with steps set to true. Example: Home;Work.
    waypointsstring
    Zero-based indexes of the coordinates to treat as waypoints (start and end of legs), semicolon-separated. Must include 0 and the last index. Other coordinates only shape the path. Example: 0;2.
  • mapbox_geocode_batchRun many forward, structured and reverse geocoding queries in one Mapbox Geocoding v6 request.Read-only

    Batch Geocode

    Run many forward, structured and reverse geocoding queries in one Mapbox Geocoding v6 request. Returns batch, an array with one GeoJSON FeatureCollection per query in the order sent; a query with no match has an empty features array. Use mapbox_geocode_batch for a list of addresses or coordinates. Use mapbox_geocode_forward or mapbox_geocode_reverse for a single lookup.

    Inputs

    queriesarrayrequired
    The geocoding queries to run, in order. Each item is one forward query (q plus optional filters such as types, country, bbox, proximity or limit), one structured query (address_number, street, place, region, postcode, country and so on) or one reverse query (longitude and latitude). Filters with several values can be arrays or comma-separated strings. Mapbox documents up to 1000 queries per request, but its error table also names a 50-query limit, so send 50 or fewer per call. Each query is billed as one Geocoding request. Example: [{"q": "1600 Pennsylvania Avenue NW, Washington, DC 20500", "types": ["address"], "limit": 1}, {"longitude": -73.986136, "latitude": 40.748895, "types": ["address"]}].
    permanentboolean
    Set true when you intend to store the results (permanent geocoding). Permanent geocoding needs a credit card on file or an enterprise contract on the Mapbox account and is billed at a different rate. Defaults to false (temporary results that must not be cached). Example: false.
  • mapbox_geocode_forwardConvert an address or place name in free text into coordinates with Mapbox Geocoding v6.Read-only

    Geocode Address

    Convert an address or place name in free text into coordinates with Mapbox Geocoding v6. Returns a GeoJSON FeatureCollection; each feature has the coordinates, full_address, feature_type, match_code and the context (street, place, region, postcode, country). Use mapbox_geocode_forward for one free-text address. Use mapbox_geocode_forward_structured when the address is already split into parts, mapbox_geocode_batch for many addresses, and mapbox_search_forward to find businesses and points of interest, which Geocoding v6 does not return.

    Inputs

    qstringrequired
    The address or place to look up, such as a full address, a city or a postcode. At most 256 characters and 20 words, with no semicolon. Example: 2 Lincoln Memorial Circle SW, Washington, DC.
    autocompleteboolean
    Set false to return only exact matches instead of results that start with the query (true is the default). Use false for complete addresses. Example: false.
    bboxstring
    Limit results to a bounding box, as four comma-separated numbers in minLon,minLat,maxLon,maxLat order. The box cannot cross the 180th meridian. Example: -74.27,40.49,-73.68,40.92.
    countrystring
    Limit results to one or more countries, as comma-separated ISO 3166 alpha-2 codes. Example: us,ca.
    languagestring
    Language of the returned text, as an IETF language tag. List several, comma-separated, to get translations; the first is the primary language. Example: en.
    limitinteger
    Maximum number of results, from 1 to 10. Defaults to 5. Example: 3.
    permanentboolean
    Set true when you intend to store the results (permanent geocoding). Permanent geocoding needs a credit card on file or an enterprise contract on the Mapbox account and is billed at a different rate. Defaults to false (temporary results that must not be cached). Example: false.
    proximitystring
    Bias results toward a location, as longitude,latitude, or the string ip to bias by the caller's IP address. Example: -73.99,40.73.
    typesstring
    Return only these feature types, comma-separated. Options: country, region, postcode, district, place, locality, neighborhood, street and address. Example: address,street.
    worldviewstring
    Return boundaries and names as seen by a regional audience. Defaults to us. Example: in.one of arcninjpmarsrutrus
  • mapbox_geocode_forward_structuredConvert an address that is already split into parts (house number, street, city, region, postcode, country) into coordinates with Mapbox Geocoding v6.Read-only

    Geocode Structured Address

    Convert an address that is already split into parts (house number, street, city, region, postcode, country) into coordinates with Mapbox Geocoding v6. Returns a GeoJSON FeatureCollection; each feature has the coordinates, full_address, feature_type, match_code and context. Use mapbox_geocode_forward_structured when you have address fields from a form or database; give at least one address part. Use mapbox_geocode_forward for a single free-text address.

    Inputs

    address_line1string
    House number and street in one line. Use this or address_number and street. Example: 1600 Pennsylvania Ave NW.
    address_numberstring
    House number on its own, used with street. Example: 1600.
    autocompleteboolean
    Set false to return only exact matches; Mapbox recommends false for structured input. Defaults to true. Example: false.
    bboxstring
    Limit results to a bounding box, as four comma-separated numbers in minLon,minLat,maxLon,maxLat order. The box cannot cross the 180th meridian. Example: -74.27,40.49,-73.68,40.92.
    blockstring
    Block, an address component in some countries such as Japan. Example: 1丁目.
    countrystring
    Country as an ISO 3166 alpha-2 code, which strictly filters results, or a full country name, which only biases them. Example: us.
    languagestring
    Language of the returned text, as an IETF language tag. List several, comma-separated, to get translations; the first is the primary language. Example: en.
    limitinteger
    Maximum number of results, from 1 to 10. Defaults to 5. Example: 1.
    localitystring
    Official sub-city area used in postal addresses in some countries, such as an arrondissement in France. Example: 7e Arrondissement.
    neighborhoodstring
    Neighborhood name. Example: Foggy Bottom.
    permanentboolean
    Set true when you intend to store the results (permanent geocoding). Permanent geocoding needs a credit card on file or an enterprise contract on the Mapbox account and is billed at a different rate. Defaults to false (temporary results that must not be cached). Example: false.
    placestring
    City, town or village. Example: Washington.
    postcodestring
    Postal code. Example: 20500.
    proximitystring
    Bias results toward a location, as longitude,latitude, or the string ip to bias by the caller's IP address. Example: -73.99,40.73.
    regionstring
    State, province or other top-level region. Example: DC.
    streetstring
    Street name on its own, used with address_number. Example: Pennsylvania Ave NW.
    typesstring
    Return only these feature types, comma-separated. Options: country, region, postcode, district, place, locality, neighborhood, street and address. Example: address,street.
    worldviewstring
    Return boundaries and names as seen by a regional audience. Defaults to us. Example: in.one of arcninjpmarsrutrus