Skip to main content
Glama
Mapbox MCP Server

Mapbox MCP Server

Official
by mapbox

Directions Tool

directions_tool
Read-onlyIdempotent

Fetches Mapbox routes from coordinates and a routing profile, returning distance, duration, turn-by-turn instructions, and a route ref for map rendering.

Instructions

Fetches directions from Mapbox API based on provided coordinates and direction method. Returns a mapboxRender.ref in structuredContent regardless of the geometries value; if the user wants to see the route on a map, pass it to render_map_tool. Use geometries="none" (default) for compact text/data responses (distance, duration, turn-by-turn instructions, congestion). Use geometries="geojson" when you need the raw route coordinates in the response yourself, e.g. to draw the route in your own app. It defaults to a simplified geometry that keeps the route's shape when zoomed out but cuts corners up close; pass overview="full" for every vertex when your map lets people zoom in on the route. render_map_tool works either way. Only overview="full" on a very long trip can exceed the response size limit; then this tool returns a summary and a mapbox://response/... ref you can read with the MCP resources API.

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>"
    },
    "name": "directions_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
excludeNoWhether to exclude certain road types and custom locations from routing. Multiple values can be specified as a comma-separated list. Available options: - All profiles: ferry, cash_only_tolls - Driving/Driving-traffic profiles only: motorway, toll, unpaved, tunnel, country_border, state_border or point(<lng> <lat>) For custom locations you can use Point exclusions (note lng and lat are space separated and at most 50 points are allowed) Note: country_border excludes all controlled country borders; borders within the Schengen Area are not excluded.
overviewNoDetail level of the geometry named above (has no effect when geometries="none", since no geometry is returned either way). Defaults to "simplified" when geometries="geojson" (a route across an entire country is typically well under 100 coordinate pairs — enough to draw an accurate shape, not enough to bloat the response) and to "full" otherwise. Pass "full" explicitly for the maximum-precision geometry (every road segment vertex) if you need it, e.g. for a map people zoom in on; on a long trip this can be tens of thousands of coordinate pairs, at which point the response no longer fits in this reply and this tool returns a summary and a `mapbox://response/` ref instead (see the tool description). Note: the Directions API cannot return per-segment congestion data (`congestion_information` in the response) together with anything other than "full" — congestion is only included when the effective overview is "full".
arrive_byNoThe desired arrival time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mmss±hh:mm, or YYYY-MM-DDThh:mm). This parameter is only available for the driving profile and is not supported by other profiles, not even driving-traffic. The travel time will be calculated based on historical and real-time traffic data.
depart_atNoThe departure time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mmss±hh:mm, or YYYY-MM-DDThh:mm). This parameter is only available for the driving and driving-traffic profiles. The travel time will be calculated based on historical and real-time traffic data.
max_widthNoThe max vehicle width, in meters. The Directions API will compute a route that includes only roads with a width limit greater than or equal to the max vehicle width. Must be between 0 and 10 meters. The default value is 1.9 meters. Only available for driving and driving-traffic profiles.
geometriesNoThe format of the returned geometry. Options: - none (default): no geometry object is returned in the response. The mapboxRender.ref works with render_map_tool either way; use this whenever you do not need the raw coordinates yourself. - geojson: as a GeoJSON LineString, always returned directly in this response — the coordinate count depends on `overview` (see below), not on trip length, so this works the same way for a 2-mile trip and a 400-mile one. Use this whenever you (the caller) need the coordinates yourself, e.g. to draw the route in your own app; not required for render_map_tool.none
max_heightNoThe max vehicle height, in meters. The Directions API will compute a route that includes only roads with a height limit greater than or equal to the max vehicle height. Must be between 0 and 10 meters. The default value is 1.6 meters. Only available for driving and driving-traffic profiles.
max_weightNoThe max vehicle weight, in metric tons (1000 kg). The Directions API will compute a route that includes only roads with a weight limit greater than or equal to the max vehicle weight. Must be between 0 and 100 metric tons. The default value is 2.5 metric tons. Only available for driving and driving-traffic profiles.
coordinatesYesArray of coordinate objects with longitude and latitude properties to visit in order. Must include at least 2 coordinate pairs (starting and ending points). Up to 25 coordinates total are supported.
alternativesNoWhether to try to return alternative routes (true) or not (false, default). Up to two alternatives may be returned.
routing_profileNoRouting profile for different modes of transport. Options: - mapbox/driving-traffic (default): automotive with current traffic conditions - mapbox/driving: automotive based on typical traffic - mapbox/walking: pedestrian/hiking - mapbox/cycling: bicyclemapbox/driving-traffic

Output Schema

NameRequiredDescriptionDefault
codeNo
uuidNo
routesNo
waypointsNo
mapboxRenderNoMap-payload reference for `render_map_tool`. Surfaced so the LLM can chain the next call without re-emitting geometry.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed42 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"
    • changedInput schema / properties / geometries / description
      Previous value: -"The format of the returned geometry. Options: \n- none (default): no geometry object is returned at all, use this if you do not need all of the intermediate coordinates.\n- geojson: as GeoJSON LineString (might be very long as there could be a lot of points)"New value: +"The format of the returned geometry. Options: \n- none (default): no geometry object is returned in the response. The mapboxRender.ref works with render_map_tool either way; use this whenever you do not need the raw coordinates yourself.\n- geojson: as a GeoJSON LineString, always returned directly in this response — the coordinate count depends on `overview` (see below), not on trip length, so this works the same way for a 2-mile trip and a 400-mile one. Use this whenever you (the caller) need the coordinates yourself, e.g. to draw the route in your own app; not required for render_map_tool."
    • addedInput schema / properties / overview
      Added value: +{
      +  "description": "Detail level of the geometry named above (has no effect when geometries=\"none\", since no geometry is returned either way). Defaults to \"simplified\" when geometries=\"geojson\" (a route across an entire country is typically well under 100 coordinate pairs — enough to draw an accurate shape, not enough to bloat the response) and to \"full\" otherwise. Pass \"full\" explicitly for the maximum-precision geometry (every road segment vertex) if you need it, e.g. for a map people zoom in on; on a long trip this can be tens of thousands of coordinate pairs, at which point the response no longer fits in this reply and this tool returns a summary and a `mapbox://response/` ref instead (see the tool description). Note: the Directions API cannot return per-segment congestion data (`congestion_information` in the response) together with anything other than \"full\" — congestion is only included when the effective overview is \"full\".",
      +  "enum": [
      +    "full",
      +    "simplified"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +{}
    • addedOutput schema / properties / mapboxRender
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Map-payload reference for `render_map_tool`. Surfaced so the LLM can chain the next call without re-emitting geometry.",
      +  "properties": {
      +    "ref": {
      +      "description": "Server-side payload reference. Pass to `render_map_tool` via `payload_refs: [\"<this ref>\"]` to display the data on a live Mapbox GL JS map, or, in ChatGPT Desktop, to the `redraw_map` tool of the open Mapbox map.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "ref"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / properties / routes / items / properties / duration_typical / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / routes / items / properties / duration_typical / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • changedOutput schema / properties / routes / items / properties / geometry / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "coordinates": {
      -        "items": {
      -          "anyOf": [
      -            {
      -              "items": [
      -                {
      -                  "type": "number"
      -                },
      -                {
      -                  "type": "number"
      -                }
      -              ],
      -              "type": "array"
      -            },
      -            {
      -              "items": [
      -                {
      -                  "type": "number"
      -                },
      -                {
      -                  "type": "number"
      -                },
      -                {
      -                  "type": "number"
      -                }
      -              ],
      -              "type": "array"
      -            }
      -          ]
      -        },
      -        "type": "array"
      -      },
      -      "type": {
      -        "const": "LineString",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "type",
      -      "coordinates"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "coordinates": {
      +        "items": {
      +          "anyOf": [
      +            {
      +              "items": false,
      +              "maxItems": 2,
      +              "minItems": 2,
      +              "prefixItems": [
      +                {
      +                  "type": "number"
      +                },
      +                {
      +                  "type": "number"
      +                }
      +              ],
      +              "type": "array"
      +            },
      +            {
      +              "items": false,
      +              "maxItems": 3,
      +              "minItems": 3,
      +              "prefixItems": [
      +                {
      +                  "type": "number"
      +                },
      +                {
      +                  "type": "number"
      +                },
      +                {
      +                  "type": "number"
      +                }
      +              ],
      +              "type": "array"
      +            }
      +          ]
      +        },
      +        "type": "array"
      +      },
      +      "type": {
      +        "const": "LineString",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "type",
      +      "coordinates"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedOutput schema / properties / routes / items / properties / legs / items / properties / annotation / properties / congestion_numeric / items / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / annotation / properties / congestion_numeric / items / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / routes / items / properties / legs / items / properties / duration_typical / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / duration_typical / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / routes / items / properties / legs / items / properties / notifications / items / properties / details / properties / actual_value / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / notifications / items / properties / details / properties / actual_value / type
      Added value: +[
      +  "string",
      +  "number"
      +]
    • removedOutput schema / properties / routes / items / properties / legs / items / properties / notifications / items / properties / details / properties / requested_value / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / notifications / items / properties / details / properties / requested_value / type
      Added value: +[
      +  "string",
      +  "number"
      +]
    • removedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / duration_typical / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / duration_typical / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • changedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / geometry / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "coordinates": {
      -        "items": {
      -          "anyOf": [
      -            {
      -              "items": [
      -                {
      -                  "type": "number"
      -                },
      -                {
      -                  "type": "number"
      -                }
      -              ],
      -              "type": "array"
      -            },
      -            {
      -              "items": [
      -                {
      -                  "type": "number"
      -                },
      -                {
      -                  "type": "number"
      -                },
      -                {
      -                  "type": "number"
      -                }
      -              ],
      -              "type": "array"
      -            }
      -          ]
      -        },
      -        "type": "array"
      -      },
      -      "type": {
      -        "const": "LineString",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "type",
      -      "coordinates"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "coordinates": {
      +        "items": {
      +          "anyOf": [
      +            {
      +              "items": false,
      +              "maxItems": 2,
      +              "minItems": 2,
      +              "prefixItems": [
      +                {
      +                  "type": "number"
      +                },
      +                {
      +                  "type": "number"
      +                }
      +              ],
      +              "type": "array"
      +            },
      +            {
      +              "items": false,
      +              "maxItems": 3,
      +              "minItems": 3,
      +              "prefixItems": [
      +                {
      +                  "type": "number"
      +                },
      +                {
      +                  "type": "number"
      +                },
      +                {
      +                  "type": "number"
      +                }
      +              ],
      +              "type": "array"
      +            }
      +          ]
      +        },
      +        "type": "array"
      +      },
      +      "type": {
      +        "const": "LineString",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "type",
      +      "coordinates"
      +    ],
      +    "type": "object"
      +  }
      +]
    • changedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / intersections / items / properties / location / items
      Previous value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]New value: +false
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / intersections / items / properties / location / maxItems
      Added value: +2
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / intersections / items / properties / location / minItems
      Added value: +2
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / intersections / items / properties / location / prefixItems
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
    • changedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / maneuver / properties / location / items
      Previous value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]New value: +false
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / maneuver / properties / location / maxItems
      Added value: +2
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / maneuver / properties / location / minItems
      Added value: +2
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / maneuver / properties / location / prefixItems
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
    • removedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / weight_typical / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / steps / items / properties / weight_typical / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / routes / items / properties / legs / items / properties / weight_typical / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / routes / items / properties / legs / items / properties / weight_typical / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • changedOutput schema / properties / routes / items / properties / waypoints / items / properties / location / items
      Previous value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]New value: +false
    • addedOutput schema / properties / routes / items / properties / waypoints / items / properties / location / maxItems
      Added value: +2
    • addedOutput schema / properties / routes / items / properties / waypoints / items / properties / location / minItems
      Added value: +2
    • addedOutput schema / properties / routes / items / properties / waypoints / items / properties / location / prefixItems
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
    • removedOutput schema / properties / routes / items / properties / weight_typical / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / routes / items / properties / weight_typical / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • changedOutput schema / properties / waypoints / items / properties / snap_location / items
      Previous value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]New value: +false
    • addedOutput schema / properties / waypoints / items / properties / snap_location / maxItems
      Added value: +2
    • addedOutput schema / properties / waypoints / items / properties / snap_location / minItems
      Added value: +2
    • addedOutput schema / properties / waypoints / items / properties / snap_location / prefixItems
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
  2. First observedv0.12.6

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so the description focuses on behavior annotations cannot express: a mapboxRender.ref is always returned regardless of geometries, and oversized responses degrade to a summary plus a mapbox://response/... resource ref. It also warns which option combinations trigger that size limit, which is exactly the operational risk an agent needs to know.

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

Conciseness4/5

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

Front-loaded with purpose, then the ref handoff, then the geometries guidance, then the failure mode — a sensible order with no filler sentences. It is dense and somewhat long, and parts of the overview/geometry guidance are echoed in the parameter schema, but nothing is purely redundant.

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

Completeness5/5

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

With 11 parameters, full schema coverage, an output schema, and rich annotations, the remaining burden is the cross-cutting behavior — the render ref, the geometry/overview tradeoff, and the response-size fallback — and the description covers all three. An agent can call this correctly and interpret the degraded-response case without further help.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3; the description earns above that by framing the geometries/overview interaction as a decision rather than restating types. It explains the default simplified geometry's tradeoff (shape preserved when zoomed out, corners cut up close) and the congestion caveat, adding meaning beyond the schema text.

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

Purpose5/5

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

States a specific verb and resource ('Fetches directions from Mapbox API') and immediately scopes it to coordinates plus direction method. It also names the sibling render_map_tool and the handoff artifact (mapboxRender.ref), so an agent can place this tool in the workflow without opening a schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use rules for the key branching decisions: geometries="none" (default) for compact text/data, geometries="geojson" only when the caller needs coordinates itself, and overview="full" only when the map zooms in. It also states render_map_tool works either way, removing a common false dependency.

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