在 AI 应用中集成 Mapbox MCP Server…

当需要给 AI 应用或 Agent 框架（pydantic-ai、mastra、LangChain、自定义 Agent）接入地理空间能力时，用 Mapbox MCP Server 的工具分类与接入模式来选型和集成。

适用场景

解决思路

1. 先区分工具类别再让 LLM 选择：直线距离类（distance_tool、bearing_tool、midpoint_tool，离线即时）用于邻近判断、『X 有多远』、距离比较；路线距离类（directions_tool、matrix_tool，走 API、含路况）用于导航、驾车时长、『开车要多久』。
2. 搜索类区分类型与具体地点：按类别/类型搜索用 category_search_tool（如『找咖啡店』『附近的餐厅』）；具体地点或地址用 search_and_geocode_tool、reverse_geocode_tool（如『找 123 Main Street』）。
3. 出行时间区分可达区域与具体路线：可达范围用 isochrone_tool，返回 GeoJSON 多边形表示某时间内可达的全部区域（如『15 分钟内能到哪』）；具体路线用 directions_tool，返回到某一目的地的逐向导航（如『怎么去机场』）。
4. 按成本与性能选择：离线工具（distance_tool、point_in_polygon_tool、area_tool 等）免费、即时、不消耗 token，不需要实时数据时优先使用；API 工具（directions_tool、category_search_tool、isochrone_tool 等）需要 token 并计入用量，仅在需要实时路况、实时 POI 数据或路径规划时使用。
5. 接入方式优先选托管服务器：使用 Mapbox 托管 MCP 服务器 https://mcp.mapbox.com/mcp，无需安装，在 Authorization 头中传 Mapbox access token，即 Authorization: Bearer your_mapbox_token；托管服务器也支持 OAuth，但主要用于交互式流程（编码助手），不用于生产应用。
6. 自托管方式：执行 npm install @mapbox/mcp-server，或直接用 npx @mapbox/mcp-server 运行；设置环境变量 export MAPBOX_ACCESS_TOKEN="your_token_here"。
7. 按任务加载对应的参考文件：Pydantic AI 加载 references/pydantic-ai.md；CrewAI 加载 references/crewai.md；Smolagents 加载 references/smolagents.md；Mastra 加载 references/mastra.md；LangChain 加载 references/langchain.md；自定义 Agent（Zillow/TripAdvisor/DoorDash 风格模式、架构图、混合方案）加载 references/custom-agent.md；用例（房地产、外卖、旅行规划）加载 references/use-cases.md；生产模式（缓存、批量操作、工具描述、错误处理、安全、限流、测试）加载 references/production.md。
8. 了解可用工具范围：离线工具（Turf.js）包括距离、方位角、中点计算，点在多边形内判断，面积、缓冲区、质心操作，边界框、几何简化，无 API 调用、即时返回；Mapbox API 工具包括路径规划与导航、反向地理编码、POI 类别搜索、等时圈（可达性）、出行时间矩阵、静态地图图片、GPS 轨迹地图匹配、多站点路线优化；工具类还包括服务器版本信息和 POI 类别列表。

适用边界 · 注意事项

• 需要实时路况、实时 POI 数据或路径规划时，不要用离线工具，应改用 API 工具。
• 生产应用中不要用 OAuth 认证，应使用 token 认证（Authorization: Bearer）。
• 不需要实时数据时不要调用 API 工具，以免消耗 token 和额度。