How to Use the Mapbox MCP in OpenAI Agents SDK

Q: How does the OpenAI Agents SDK use Mapbox to calculate multi-stop routes?

Your agent calls the getdistancematrix tool to get travel times between all points. The OpenAI agent then uses that data to determine the optimal sequence for the stops. The SDK's built-in tracing lets you review exactly how it made its decision.

Q: Is geocoding with Mapbox via the OpenAI Agents SDK asynchronous?

It is. You connect to the MCP Server using an async with context manager, which means calls to tools like geocode or getdirections won't block your main application thread. This is essential for building responsive, production-grade agents.

Q: How is my location data handled when using Mapbox with the OpenAI Agents SDK?

Your agent sends location data, like addresses for geocode or coordinates for getdirections, through Vinkius to the Mapbox APIs. Vinkius servers are ephemeral and don't store your request data after the transaction completes. All communication is secured with TLS.

Build production-ready logistics agents with Mapbox and the OpenAI Agents SDK. Get routes, find coordinates, and trace every action.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Mapbox MCP to OpenAI Agents SDK

Create your Vinkius account to connect Mapbox to OpenAI Agents SDK and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Mapbox with OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Coordinate Specialized Agents

Build agentic systems where each agent has a specific job. One agent can use the `geocode` tool to turn an address into coordinates. It then hands off those coordinates to a routing specialist agent that calls `get_directions` or `get_distance_matrix` to plan the trip. This entire workflow is visible in the OpenAI trace dashboard. You can even have an agent generate a map with `get_static_map` and include the image URL in its output for quick visual checks. Every decision, every tool call, is logged and auditable.

Add Guardrails to Geographic Actions

The OpenAI Agents SDK lets you wrap agent actions in safety checks. Before your agent fires off a request to `get_distance_matrix` for 100 locations, your guardrail can validate the input to prevent a costly or slow operation. It's a simple way to enforce budgets and usage policies. These rules also ensure operational correctness. You can force an agent to use the `mapbox/walking` profile for any route under two kilometers, or prevent it from using `get_elevation` outside a specific geographic boundary. This MCP Server provides the tools; the SDK makes sure your agent uses them right.

Auto-Discover Mapbox Tools with Your OpenAI MCP Server

There's no need to manually define tool schemas. Just connect your agent to this MCP Server, and it automatically discovers all eight Mapbox tools and their parameters. Your agent will know exactly how to structure a call to `search_nearby` or `reverse_geocode` from the start. Set `cacheToolsList=True` during setup for better performance. After the first run, your agent won't need to fetch the tool list again. It gets straight to work, turning place names into coordinates and planning routes.

Setup guide

Set up Mapbox MCP in OpenAI Agents SDK

Prerequisites

Python 3.10+ installed
openai-agents package (pip install openai-agents)
Active Vinkius subscription with a valid endpoint token

1

Install the SDK

Run pip install openai-agents to install the OpenAI Agents SDK. The MCP integration is built-in — no extra dependencies needed.
2

Connect via SSE transport

Use MCPServerSse with your Vinkius endpoint URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. The SDK auto-discovers all Mapbox tools at runtime.
3

Create your Agent

Pass the MCP to Agent(mcp_servers=[server]). The agent receives Mapbox tools as native definitions — JSON schemas resolve automatically.
4

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate Mapbox tools and returns structured results. Copy the full example on the right to get started.

agent.py

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    async with MCPServerSse(
        url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    ) as server:
        agent = Agent(
            name="Mapbox Agent",
            instructions="You have access to Mapbox tools.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "List recent transactions")
        print(result.final_output)

asyncio.run(main())

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Mapbox. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Mapbox now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Mapbox MCP in OpenAI Agents SDK

Your agent calls the `get_distance_matrix` tool to get travel times between all points. The OpenAI agent then uses that data to determine the optimal sequence for the stops. The SDK's built-in tracing lets you review exactly how it made its decision.

Yes. While the MCP Server exposes all tools, you can write a guardrail function in your agent's code. This function checks the tool name before execution and can block calls to, for instance, `get_static_map` if you only want the agent to perform routing tasks.

It is. You connect to the MCP Server using an `async with` context manager, which means calls to tools like `geocode` or `get_directions` won't block your main application thread. This is essential for building responsive, production-grade agents.

The MCP Server provides a standard interface. Your OpenAI agent can switch between this and other MCP-compatible services without changing its core logic. Vinkius also manages authentication and infrastructure, so you just give the agent a single endpoint token.

Your agent sends location data, like addresses for `geocode` or coordinates for `get_directions`, through Vinkius to the Mapbox APIs. Vinkius servers are ephemeral and don't store your request data after the transaction completes. All communication is secured with TLS.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript