/mapbox-mcp-runtime-patterns

Mapbox MCP Runtime Integration Examples

Working, compilable examples showing how to integrate Mapbox MCP Server with popular agent frameworks.

Prerequisites

1. Mapbox Access Token: Get one at mapbox.com/account/access-tokens
2. OpenAI API Key (or other LLM provider)
3. HuggingFace Token (for smolagents)

Python Examples

Setup

cd python
pip install -r requirements.txt

# Set environment variables
export MAPBOX_ACCESS_TOKEN="your_token_here"
export OPENAI_API_KEY="your_openai_key"
export HF_TOKEN="your_huggingface_token"  # For smolagents

1. Pydantic AI Example

Framework: Pydantic AI - Type-safe agents with validation

python pydantic_ai_example.py

Features:

• Type-safe tool definitions
• Environment variable support
• Hosted MCP server integration
• Real-world examples (restaurant finder, route planning)

Best for: Production applications requiring type safety and validation

2. CrewAI Example

Framework: CrewAI - Multi-agent orchestration

python crewai_example.py

Features:

• Multi-agent crews with specialized roles
• Task dependencies and context passing
• Location Analyst + Route Planner agents
• Real-world examples (restaurant crew, property search)

Best for: Complex workflows requiring multiple specialized agents

Agents included:

• Location Analyst: Finds places, analyzes areas
• Route Planner: Calculates routes and travel times

3. Smolagents Example

Framework: Smolagents - Hugging Face's lightweight agents

python smolagents_example.py

Features:

• Method 1: Direct MCP connection (recommended, minimal code)
• Method 2: Custom tools with @tool decorator
• Lightweight and fast
• Real-world example (property search agent)

Best for: Production deployment with minimal overhead

Note: Smolagents has native MCP support via MCPClient!

TypeScript Examples

Setup

cd typescript
npm install

# Set environment variables
export MAPBOX_ACCESS_TOKEN="your_token_here"
export OPENAI_API_KEY="your_openai_key"

1. Mastra Example

Framework: Mastra 1.x - Modern TypeScript agent framework

npm run mastra

Features:

• Type-safe tool creation with Zod schemas
• Hosted MCP server integration
• Multiple Mapbox tools (directions, POI search, distance, isochrone)
• Real-world examples

Best for: TypeScript applications with strong typing

Tools included:

• get-directions: Driving directions with traffic
• search-poi: Find restaurants, hotels, etc.
• calculate-distance: Offline distance calculation
• get-isochrone: Reachable area analysis

Verify it compiles:

npm run build  # TypeScript type-check

2. LangChain Example

Framework: LangChain - Conversational AI framework

npm run langchain

Features:

• Conversational interface
• Tool chaining
• Memory and context management
• Multi-step workflows

Best for: Conversational applications with complex tool chains

Tools included:

• Directions, POI search, distance calculation, isochrones
• All tools use hosted Mapbox MCP server

Framework Comparison

Common Use Cases

1. Restaurant Finder

Find restaurants near a location with distances:

• Pydantic AI: pydantic_ai_example.py (Example 1)
• CrewAI: crewai_example.py (Example 1)
• LangChain: langchain-example.ts (Example 3)

2. Route Planning

Calculate driving time with traffic:

• Pydantic AI: pydantic_ai_example.py (Example 2)
• Mastra: mastra-example.ts (Example 2)

3. Property Search

Find properties with good commute:

• CrewAI: crewai_example.py (Example 2)
• Smolagents: smolagents_example.py (Example 3)

Mapbox MCP Tools Available

All examples connect to the hosted Mapbox MCP Server at https://mcp.mapbox.com/mcp.

API Tools (require Mapbox token):

• directions_tool: Driving directions with traffic
• category_search_tool: Find POIs by category
• search_and_geocode_tool: Search for specific places or addresses
• reverse_geocode_tool: Coordinates to address
• isochrone_tool: Reachable area within time
• matrix_tool: Travel time matrix
• static_map_image_tool: Static map images
• map_matching_tool: Match GPS traces to roads
• optimization_tool: Optimize multi-stop routes

Offline Tools (free, instant):

• distance_tool: Distance between points
• bearing_tool: Compass direction
• midpoint_tool: Midpoint between points
• point_in_polygon_tool: Point containment test
• area_tool: Polygon area
• centroid_tool: Polygon center
• buffer_tool: Create buffer zones
• bbox_tool: Calculate bounding boxes
• simplify_tool: Simplify geometries

Utility Tools:

• version_tool: Get MCP server version
• category_list_tool: List available POI categories

Testing Examples

Python

# Run all Python examples
cd python
python pydantic_ai_example.py
python crewai_example.py
python smolagents_example.py

TypeScript

# Type-check all TypeScript examples
cd typescript
npm run build

# Run individual examples
npm run mastra
npm run langchain

Troubleshooting

Missing MAPBOX_ACCESS_TOKEN

Error: MAPBOX_ACCESS_TOKEN is required

Solution: Export the environment variable

export MAPBOX_ACCESS_TOKEN="pk.ey..."

MCP Connection Failed

Error: MCP request failed: Unauthorized

Solution: Check your token has proper scopes at mapbox.com/account/access-tokens

Import Errors (Python)

ModuleNotFoundError: No module named 'crewai'

Solution: Install requirements

pip install -r requirements.txt

TypeScript Compilation Errors

Cannot find module '@mastra/core'

Solution: Install dependencies

npm install

Resources

• Mapbox MCP Server
• Mapbox MCP DevKit
• Model Context Protocol
• Pydantic AI Docs
• CrewAI Docs
• Smolagents Docs
• Mastra Docs
• LangChain Docs

Contributing

Found an issue or want to add more examples? Please open a PR!

License

These examples are provided as-is for educational purposes.