Mapbox Mcp Runtime Patterns

# Mapbox MCP Runtime Patterns

Quick reference for integrating Mapbox MCP Server into AI applications for production use.

## What is MCP Server?

Runtime server providing geospatial tools to AI agents via Model Context Protocol.

**Repo:** <https://github.com/mapbox/mcp-server>

## Tools Available

| Category              | Tools                                                                                                                                                                                            | Cost            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| **Offline (Turf.js)** | `distance_tool`, `bearing_tool`, `midpoint_tool`, `point_in_polygon_tool`, `area_tool`, `buffer_tool`, `centroid_tool`, `bbox_tool`, `simplify_tool`                                             | Free, instant   |
| **Mapbox APIs**       | `directions_tool`, `search_and_geocode_tool`, `reverse_geocode_tool`, `category_search_tool`, `isochrone_tool`, `matrix_tool`, `static_map_image_tool`, `map_matching_tool`, `optimization_tool` | API costs apply |
| **Utility**           | `version_tool`, `category_list_tool`                                                                                                                                                             | Free            |

## Coordinate Formats

All tools use `{longitude, latitude}` object format — **not** arrays.

**Object format** `{longitude: lng, latitude: lat}`:

- `directions_tool` - `coordinates` array of objects
- `isochrone_tool` - `coordinates` parameter
- `reverse_geocode_tool` - `coordinates` parameter
- `category_search_tool` - `proximity` parameter
- `distance_tool` - `from`/`to` parameters
- `bearing_tool` - `from`/`to` parameters
- `midpoint_tool` - `from`/`to` parameters
- `point_in_polygon_tool` - `point` parameter

**Exception — GeoJSON geometry** (arrays only):

- `buffer_tool` - `geometry` parameter uses `[longitude, latitude]` arrays (GeoJSON format)
- `point_in_polygon_tool` - `polygon` rings use `[longitude, latitude]` arrays

**Note:** All coordinates use `longitude` before `latitude` order.

## Installation

### Hosted (Recommended)

Use Mapbox's hosted server - no installation needed:

```
https://mcp.mapbox.com/mcp
```

Connect with your token in the `Authorization: Bearer <token>` header.

**Note:** Hosted server supports OAuth for interactive flows (coding assistants), but use token auth for programmatic runtime access.

### Self-Hosted

```bash
npm install @mapbox/mcp-server
# Or: npx @mapbox/mcp-server

export MAPBOX_ACCESS_TOKEN="your_token"
```

## Framework Integration

### Pydantic AI

```python
from pydantic_ai import Agent
import subprocess

# Start MCP server
mcp = subprocess.Popen(['npx', '@mapbox/mcp-server'],
                       env={'MAPBOX_ACCESS_TOKEN': token})

agent = Agent(
    model='gateway/openai:gpt-5.2',
    tools=[
        lambda from_loc, to_loc: call_mcp('directions_tool', {
            'origin': from_loc,
            'destination': to_loc
        })
    ]
)
```

### Mastra

```typescript
import { spawn } from 'child_process';

const mcp = spawn('npx', ['@mapbox/mcp-server'], {
  env: { MAPBOX_ACCESS_TOKEN: process.env.MAPBOX_ACCESS_TOKEN }
});

const mastra = new Mastra({
  workflows: {
    findRestaurants: {
      steps: [
        { tool: 'mapbox.category_search_tool', input: {...} },
        { tool: 'mapbox.matrix_tool', input: {...} }
      ]
    }
  }
});
```

### LangChain

```typescript
import { DynamicTool } from '@langchain/core/tools';

const tools = [
  new DynamicTool({
    name: 'directions_tool',
    description: 'Get driving directions',
    func: async (input) => {
      const { origin, destination } = JSON.parse(input);
      return await callMCP('directions_tool', { origin, destination });
    }
  })
]