Skip to main content
Glama
Mapbox MCP Server

Mapbox MCP Server

Official
by mapbox

Map Matching Tool

map_matching_tool
Read-onlyIdempotent

Snap noisy GPS traces to roads, bike paths, or walkways using Mapbox Map Matching. Clean recorded trip and fleet tracking data by returning routes aligned to the road network with confidence scores.

Instructions

Snap a recorded GPS trace to roads using Mapbox Map Matching API. Takes a dense, noisy coordinate sequence (2-100 points, recorded seconds or tens of meters apart) and returns a clean route aligned with actual roads, bike paths, or walkways. Useful for analyzing recorded trips, cleaning fleet tracking data, or processing fitness activity traces. Not for routing between a few places or addresses: points kilometers apart fail to match, so use directions_tool for that. Returns confidence scores, matched geometry, and optional traffic/speed annotations.

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": "map_matching_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
profileNoRouting profile for different modes of transport. Options: - driving: automotive based on road network - driving-traffic: automotive with current traffic conditions - walking: pedestrian/hiking - cycling: bicycledriving
overviewNoFormat of the returned geometry. Options: - full: Returns full geometry with all points - simplified: Returns simplified geometry - false: No geometry returnedfull
radiusesNoArray of maximum distances (in meters, greater than 0 and up to 50) each coordinate can snap to the road network. If provided, must have the same length as coordinates array. Default is 5 meters. Use smaller values (1-10m) for clean GPS traces, larger values (20-50m) for noisy GPS traces.
geometriesNoFormat of the returned geometry. Options: - geojson: GeoJSON LineString (recommended) - polyline: Polyline with precision 5 - polyline6: Polyline with precision 6geojson
timestampsNoArray of Unix timestamps (in seconds) corresponding to each coordinate. If provided, must have the same length as coordinates array and be in ascending order. Used to improve matching accuracy based on speed.
annotationsNoAdditional data to include in the response. Options: - speed: Speed limit per segment (km/h) - distance: Distance per segment (meters) - duration: Duration per segment (seconds) - congestion: Traffic level per segment (low, moderate, heavy, severe)
coordinatesYesArray of coordinate objects with longitude and latitude properties representing a GPS trace. Must include at least 2 and up to 100 coordinate pairs. Coordinates should be in the order they were recorded.

Output Schema

NameRequiredDescriptionDefault
codeYes
matchingsNo
tracepointsNo
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. Changed13 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 / radiuses / description
      Previous value: -"Array of maximum distances (in meters) each coordinate can snap to the road network. If provided, must have the same length as coordinates array. Default is unlimited. Use smaller values (5-25m) for high-quality GPS, larger values (50-100m) for noisy GPS traces."New value: +"Array of maximum distances (in meters, greater than 0 and up to 50) each coordinate can snap to the road network. If provided, must have the same length as coordinates array. Default is 5 meters. Use smaller values (1-10m) for clean GPS traces, larger values (20-50m) for noisy GPS traces."
    • addedInput schema / properties / radiuses / items / exclusiveMinimum
      Added value: +0
    • addedInput schema / properties / radiuses / items / maximum
      Added value: +50
    • removedInput schema / properties / radiuses / items / minimum
      Removed value: -0
    • changedInput schema / properties / timestamps / description
      Previous value: -"Array of Unix timestamps (in seconds) corresponding to each coordinate. If provided, must have the same length as coordinates array. Used to improve matching accuracy based on speed."New value: +"Array of Unix timestamps (in seconds) corresponding to each coordinate. If provided, must have the same length as coordinates array and be in ascending order. Used to improve matching accuracy based on speed."
    • 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"
      +}
    • changedOutput schema / properties / matchings / items / properties / geometry / anyOf
      Previous value: -[
      -  {
      -    "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"
      -  },
      -  {
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "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"
      +  },
      +  {
      +    "type": "string"
      +  }
      +]
    • changedOutput schema / properties / matchings / items / required
      Previous value: -[
      -  "confidence",
      -  "distance",
      -  "duration",
      -  "geometry"
      -]New value: +[
      +  "confidence",
      +  "distance",
      +  "duration"
      +]
    • changedOutput schema / properties / tracepoints / items / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "alternatives_count": {
      -        "type": "number"
      -      },
      -      "location": {
      -        "items": [
      -          {
      -            "type": "number"
      -          },
      -          {
      -            "type": "number"
      -          }
      -        ],
      -        "type": "array"
      -      },
      -      "matchings_index": {
      -        "type": "number"
      -      },
      -      "name": {
      -        "type": "string"
      -      },
      -      "waypoint_index": {
      -        "type": "number"
      -      }
      -    },
      -    "required": [
      -      "location",
      -      "matchings_index",
      -      "alternatives_count"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "alternatives_count": {
      +        "type": "number"
      +      },
      +      "location": {
      +        "items": false,
      +        "maxItems": 2,
      +        "minItems": 2,
      +        "prefixItems": [
      +          {
      +            "type": "number"
      +          },
      +          {
      +            "type": "number"
      +          }
      +        ],
      +        "type": "array"
      +      },
      +      "matchings_index": {
      +        "type": "number"
      +      },
      +      "name": {
      +        "type": "string"
      +      },
      +      "waypoint_index": {
      +        "type": "number"
      +      }
      +    },
      +    "required": [
      +      "location",
      +      "matchings_index",
      +      "alternatives_count"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / required
      Previous value: -[
      -  "code",
      -  "matchings",
      -  "tracepoints"
      -]New value: +[
      +  "code"
      +]
  2. First observedv0.12.6

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: input density expectations (points seconds or tens of meters apart), an explicit failure mode (sparse points fail to match), and what the response contains. It stops short of noting rate limits or auth requirements.

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?

Four sentences, each carrying distinct information: capability, input expectations, use cases, exclusion plus response summary. The key constraint and the sibling exclusion are front-loaded rather than buried.

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?

For a 7-parameter tool with a full output schema and rich annotations, the description covers capability, input shape, failure mode, and the routing boundary with the sibling. Nothing an agent needs to decide whether and how to call it is missing.

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 coverage is 100%, so the baseline is 3, but the description adds sampling-interval guidance ('recorded seconds or tens of meters apart') that constrains the coordinates parameter in a way the schema does not, and it flags the optional traffic/speed annotations. It does not restate per-parameter details such as the radiuses tuning advice already in the schema.

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 ('Snap a recorded GPS trace to roads') plus the underlying API, and contrasts scope with the sibling directions_tool. An agent can distinguish it from search_and_geocode_tool or directions_tool without opening any 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 positive cases (recorded trips, fleet tracking cleanup, fitness activity traces) and an explicit exclusion with the alternative named: points kilometers apart fail to match, so use directions_tool. The selection condition is fully specified.

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