Side-by-side comparison of building a Retrieval-Augmented Generation pipeline from scratch versus using the Mapbox Agents SDK.
| DIY | SDK | |
|---|---|---|
| Vector store | ~20 lines (cosine similarity by hand) | InMemoryVectorDB — zero |
| Embedding | ~5 lines | OpenAIEmbedding — one line |
A few months ago I was deep in the middle of building the Mapbox Location Agent, and I kept running into the same problem over and over. Every time I wanted the agent to do something useful with location data, I was writing boilerplate. Tool wrappers, retry logic, conversation state, multi-turn orchestration loops. The kind of stuff that has nothing to do with the actual product and everything to do with just getting the infrastructure out of the way.
At some point I looked at what we had built and realized: this is a framework. A pretty good one. And it would be a shame to keep it locked inside Mapbox.
So we're open-sourcing it. This is the story of what we built, why we built it the way we did, and how you can use it today.
End-to-end flow from user input through ContentView → AIService → external APIs, for both an initial query and a follow-up turn.
sequenceDiagram
participant U as User
participant CV as ContentView
participant AS as AIService.liveStream()
participant QP as QueryPlanner
LLMs know about the world but can't see it. Without grounding, a model will confidently invent addresses, distances, and business details — some real, some not. Grounding connects the model's outputs (and inputs) to live, verifiable data at inference time.
Mapbox is one grounding source — but not the only one, and not trying to be. The power comes from combining sources that each contribute a different layer of reality.
| name | mapbox-search-patterns |
|---|---|
| description | Expert guidance on choosing the right Mapbox search tool and parameters for geocoding, POI search, and location discovery |
Expert guidance for AI assistants on using Mapbox search tools effectively. Covers tool selection, parameter optimization, and best practices for geocoding, POI search, and location discovery.
| name | mapbox-geospatial-operations |
|---|---|
| description | Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs |
Expert guidance for AI assistants on choosing the right geospatial tools from the Mapbox MCP Server. Focuses on selecting tools based on what the problem requires - geometric calculations vs routing, straight-line vs road network, and accuracy needs.
This document explains the relationship between MCP Prompts and Agent Skills in the Mapbox MCP DevKit Server.
Prompts provide step-by-step workflows (orchestration) Skills provide domain expertise (knowledge) Tools provide capabilities (actions)