How to Use the LocationIQ MCP in OpenAI Agents SDK

Q: How does the OpenAI Agents SDK handle LocationIQ static map URLs?

The staticmap tool returns a direct URL of the map image. Your OpenAI agent receives this URL as a string and can pass it directly to user-facing channels or save it to your database.

Build production-grade spatial agents with the OpenAI Agents SDK and the LocationIQ MCP Server to route fleets and geocode addresses safely.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect LocationIQ MCP to OpenAI Agents SDK

Create your Vinkius account to connect LocationIQ 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 LocationIQ with OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Safe address resolution with OpenAI Agents SDK

The `search` tool converts raw text addresses into precise latitude and longitude coordinates directly inside your OpenAI agentic loops. When your agent parses incoming shipping data, it runs this LocationIQ tool to resolve coordinates before triggering downstream actions. If the address is partial or messy, the `autocomplete` tool steps in to predict the correct location in real-time. OpenAI's guardrails validate these spatial outputs before handing them off to your fulfillment agents, preventing bad location data from entering your system.

Multi-agent routing and nearby searches

The `directions` tool calculates exact routes and travel times between coordinates, feeding clean routing profiles to your OpenAI routing agent. By isolating this task, your primary coordination agent can delegate heavy route math to a specialized agent that only handles spatial geometry. For local discovery, the `nearby` tool queries points of interest around any set of coordinates to find refueling stops or depots. This MCP server lets your Python agents query physical geography without writing complex geospatial math libraries from scratch.

Location mapping and timezone checks

The `reverse` tool translates GPS coordinates from mobile devices into readable street addresses for instant OpenAI agent verification. Your agent can then call the `static_map` tool to generate visual map URLs, which are immediately passed to the user-facing interface for visual confirmation. To prevent timing issues, the `timezone` tool resolves the exact local time for any coordinate pair before scheduling deliveries. The OpenAI dashboard traces these calls, so you see exactly when and where your agent queried spatial data during execution.

Setup guide

Set up LocationIQ 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 LocationIQ tools at runtime.
3

Create your Agent

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

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate LocationIQ 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="LocationIQ Agent",
            instructions="You have access to LocationIQ 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 LocationIQ. 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 LocationIQ 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 LocationIQ MCP in OpenAI Agents SDK

You manage LocationIQ rate limits by setting up retry logic in your Python code or catching API exceptions during the OpenAI agent runtime. The SDK automatically traces these calls, letting you monitor throttling directly in your OpenAI dashboard.

Yes, you control tool access by filtering the LocationIQ tools list before passing them to the OpenAI Agent constructor. If you only want your agent to geocode, pass only `search` and `reverse` while leaving out the routing tools.

The `static_map` tool returns a direct URL of the map image. Your OpenAI agent receives this URL as a string and can pass it directly to user-facing channels or save it to your database.

This MCP server runs as an external HTTP service to keep your Python runtime lightweight and secure. Your OpenAI agent connects via a single endpoint, keeping your API keys safe from client-side exposure.

All coordinate and address payloads are processed in an ephemeral V8 sandbox on Vinkius before hitting the LocationIQ API. Your geographic queries are never stored or used to train models, keeping customer delivery locations private.

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