Skip to main content
Glama
Mapbox MCP Server

Mapbox MCP Server

Official
by mapbox

Matrix Tool

matrix_tool
Read-onlyIdempotent

Calculates travel times and distances between multiple points in one Mapbox Matrix API call, avoiding separate pairwise requests and supporting up to 25 coordinates.

Instructions

Calculates travel times and distances between multiple points using Mapbox Matrix API. Put all the points in one call (up to 25, 10 for driving-traffic) rather than one call per pair: the API allows 60 requests per minute (30 for driving-traffic).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "coordinates": "<coordinates>",
      "profile": "<profile>"
    },
    "name": "matrix_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
profileYesRouting profile for different modes of transport. Options: - mapbox/driving-traffic (default): automotive with current traffic conditions (limited to 10 coordinates) - mapbox/driving: automotive based on typical traffic - mapbox/walking: pedestrian/hiking - mapbox/cycling: bicycle
sourcesNoUse the coordinates at given indices as sources. Possible values are: a semicolon-separated list of 0-based indices, or "all" (default). The option "all" allows using all coordinates as sources.
bearingsNoA semicolon-separated list of headings and allowed deviation indicating the direction of movement. Input as two comma-separated values per location: a heading course measured clockwise from true north between 0 and 360, and the range of degrees by which the angle can deviate (recommended value is 45° or 90°), formatted as {angle,degrees}. If provided, the number of bearings must equal the number of coordinates. You can skip a coordinate and show its position in the list with the ; separator.
approachesNoA semicolon-separated list indicating the side of the road from which to approach waypoints. Accepts "unrestricted" (default, route can arrive at the waypoint from either side of the road) or "curb" (route will arrive at the waypoint on the driving_side of the region). If provided, the number of approaches must be the same as the number of waypoints. You can skip a coordinate and show its position with the ; separator.
annotationsNoSpecifies the resulting matrices. Possible values are: duration (default), distance, or both values separated by a comma.
coordinatesYesArray of coordinate objects with longitude and latitude properties. Must include at least 2 coordinate pairs. Up to 25 coordinates total are supported for most profiles (10 for driving-traffic).
destinationsNoUse the coordinates at given indices as destinations. Possible values are: a semicolon-separated list of 0-based indices, or "all" (default). The option "all" allows using all coordinates as destinations.

Output Schema

NameRequiredDescriptionDefault
codeYes
messageNo
sourcesYes
distancesNo
durationsNo
destinationsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed16 schema fields changedv0.18.1
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • removedOutput schema / properties / destinations / items / additionalProperties
      Removed value: -false
    • addedOutput schema / properties / destinations / items / anyOf
      Added value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "distance": {
      +        "type": "number"
      +      },
      +      "location": {
      +        "items": false,
      +        "maxItems": 2,
      +        "minItems": 2,
      +        "prefixItems": [
      +          {
      +            "type": "number"
      +          },
      +          {
      +            "type": "number"
      +          }
      +        ],
      +        "type": "array"
      +      },
      +      "name": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "name",
      +      "location",
      +      "distance"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedOutput schema / properties / destinations / items / properties
      Removed value: -{
      -  "distance": {
      -    "type": "number"
      -  },
      -  "location": {
      -    "items": [
      -      {
      -        "type": "number"
      -      },
      -      {
      -        "type": "number"
      -      }
      -    ],
      -    "type": "array"
      -  },
      -  "name": {
      -    "type": "string"
      -  }
      -}
    • removedOutput schema / properties / destinations / items / required
      Removed value: -[
      -  "name",
      -  "location",
      -  "distance"
      -]
    • removedOutput schema / properties / destinations / items / type
      Removed value: -"object"
    • removedOutput schema / properties / distances / items / items / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / distances / items / items / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / durations / items / items / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / durations / items / items / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / sources / items / additionalProperties
      Removed value: -false
    • addedOutput schema / properties / sources / items / anyOf
      Added value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "distance": {
      +        "type": "number"
      +      },
      +      "location": {
      +        "items": false,
      +        "maxItems": 2,
      +        "minItems": 2,
      +        "prefixItems": [
      +          {
      +            "type": "number"
      +          },
      +          {
      +            "type": "number"
      +          }
      +        ],
      +        "type": "array"
      +      },
      +      "name": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "name",
      +      "location",
      +      "distance"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedOutput schema / properties / sources / items / properties
      Removed value: -{
      -  "distance": {
      -    "type": "number"
      -  },
      -  "location": {
      -    "items": [
      -      {
      -        "type": "number"
      -      },
      -      {
      -        "type": "number"
      -      }
      -    ],
      -    "type": "array"
      -  },
      -  "name": {
      -    "type": "string"
      -  }
      -}
    • removedOutput schema / properties / sources / items / required
      Removed value: -[
      -  "name",
      -  "location",
      -  "distance"
      -]
    • removedOutput schema / properties / sources / items / type
      Removed value: -"object"
  2. First observedv0.12.6

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds genuinely new operational context not in the annotations: request-per-minute throttles (60, 30 for driving-traffic) and the batching implication of those limits. It omits token/auth requirements and error or cap-exceeded behavior, which would have earned a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler. What the tool does comes first, and the batching efficiency plus limits follow. Every clause carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the annotations cover safety. The description adequately conveys the one non-obvious thing an agent must know: this is a batched many-to-many call with hard caps and throttles. Auth and error handling are the only real omissions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including the enums for profile and annotations is already documented in the schema. The description's only parameter-adjacent content is restating the 25/10 coordinate caps, which the coordinates property already states. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ("Calculates") and a specific output ("travel times and distances between multiple points"), plus the upstream API it wraps. That clearly separates it from single-pair or single-route tools, though no sibling (e.g. distance_tool, directions_tool) is named to sharpen the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete usage guidance: batch all points into one call and avoid per-pair requests, with the coordinate caps and rate limits that motivate that pattern. It stops short of explicit when-not-to-use guidance or naming competing tools for single-pair or ordered-route queries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.