Mapbox MCP

Overview Geospatial context remains one of the most challenging data types for Large Language Models to handle accurately. Standard LLMs often hallucinate coordinates or fail to grasp the nuances of routing and travel times. This guide demonstrates how to bridge that gap using the Mapbox MCP (Model Context Protocol). By connecting an agent to real-time Mapbox APIs, we move beyond static knowledge and into dynamic, fact-based spatial reasoning. This technique matters because it transforms a chat interface into a functional tool capable of planning trips, visualizing data on a map, and even choreographing camera movements in a 3D environment. Prerequisites To follow this tutorial, you should have a solid grasp of **Python** and basic web development concepts. Specifically, you'll need: - A Mapbox access token for API calls. - An OpenAI API key (though the framework supports other providers). - Basic familiarity with **Flask** for creating the web interface. - **VS Code** or a similar IDE for project management. Key Libraries & Tools - Mapbox MCP: A server that provides structured tools for LLMs to access Mapbox APIs (Search, Routing, Isochrones). - CrewAI: A framework for orchestrating a "crew" of autonomous AI agents that work collaboratively. - Mapbox GL JS: A JavaScript library for rendering interactive, customizable maps in the browser. - **Flask**: A lightweight Python web framework used to serve the chat interface and the map. - **Pydantic**: Used for defining structured data schemas to ensure the agent's output is predictable. Code Walkthrough Building a sophisticated agent requires an iterative approach. We start with a single helpful assistant and evolve it into a multi-agent system that controls a live map. 1. Project Initialization and Environment Every project starts with a clean environment. You need a `.env` file to store your secrets. This keeps your tokens out of the source code and allows the Mapbox MCP to authenticate. ```python .env example MAPBOX_ACCESS_TOKEN=your_token_here OPENAI_API_KEY=your_key_here ``` 2. Defining the Crew and Agents We use CrewAI to define our agents in a YAML configuration. This separates the logic of "who the agent is" from the Python code. Initially, we define a `helpful_agent` tasked with answering general location queries. ```yaml agents.yaml helpful_agent: role: "Helpful Assistant" goal: "Assist the user with location-based queries using provided tools." backstory: "You are an expert in geography and navigation with access to real-time data." ``` In the `crew.py` file, we instantiate this agent and attach the Mapbox MCP tools. The framework automatically discovers tools from the MCP server, such as `poi_search` or `get_directions`. ```python from crewai import Agent, Crew, Task, Process Instantiate the agent with MCP tools helpful_agent = Agent( config=self.agents_config['helpful_agent'], tools=get_mcp_tools(), # Discovers tools from Mapbox MCP verbose=True ) ``` 3. Adding Structured Output for Map Visualization To move beyond text, we need a second agent: the `geo_json_enrichment_agent`. This agent's job is to take the text findings from the first agent and convert them into a valid GeoJSON object that Mapbox GL JS can render. ```python Define the structured output schema class MapOutput(BaseModel): text: str geojson: Optional[dict] = None map_commands: Optional[list] = None Update the task to require this schema geojson_task = Task( description="Convert the location findings into a GeoJSON format.", expected_output="A structured JSON object with text and GeoJSON.", output_json=MapOutput, agent=geojson_agent ) ``` 4. Choreographing the Map Camera In the final iteration, we add a `camera_choreographer_agent`. This agent produces a sequence of commands—like `flyTo`, `setFog`, or `setPaintProperty`—that the frontend interprets to create a cinematic tour. This makes the map feel alive rather than static. ```javascript // Frontend interpretation of agent commands function executeMapCommand(command) { switch(command.type) { case 'flyTo': map.flyTo({ center: command.coords, zoom: 14 }); break; case 'setSnow': map.setConfigProperty('basemap', 'snow', command.intensity); break; } } ``` Syntax Notes - **YAML for Agent Personas**: Using YAML for agent definitions is a best practice in CrewAI. It allows non-developers to tweak the agent's "personality" without touching Python code. - **Pydantic Schemas**: Notice the use of `BaseModel`. This is critical when working with LLMs. It forces the model to return a valid JSON structure, preventing the frontend from crashing due to malformed text responses. - **Template Variables**: In CrewAI, tasks use curly braces `{prompt}` to inject user input. This templating system allows the same task logic to be reused across different user queries. Practical Examples - **Real Estate Discovery**: An agent could search for schools, grocery stores, and parks within a 15-minute drive of a specific address, then highlight the overlapping "ideal" zones on the map using an isochrone tool. - **Logistics Dashboards**: A shipping agent can calculate ETAs between multiple warehouses and visualize the current traffic-influenced routes, allowing operators to see the actual path suggested by the Mapbox Directions API. - **Tourism Guides**: A "City Tour" agent can take a user's interest in "Art Deco architecture" and choreograph a flying tour over New%20York%20City, stopping at specific landmarks while adjusting the map's lighting to sunset for better visuals. Tips & Gotchas - **Token Limits with Geometry**: Do not pass massive GeoJSON objects between agents. A detailed route can have thousands of coordinates, which will exhaust your token window and increase costs. Always ask the agent to "simplify" the geometry to 10–20 key points for internal reasoning. - **Latency Management**: Multi-agent systems are sequential by nature, which is slow. To speed things up, use the `hierarchical` process in CrewAI or set certain tasks to run `async`. This allows the camera agent to start planning while the GeoJSON agent is still formatting data. - **Tool Overload**: Giving an agent too many tools can lead to confusion. If the agent struggles to pick the right API, split the tools among specialized agents (e.g., one agent for search, another for routing).