How to Use the LocationIQ MCP in Pydantic AI

Q: How does Pydantic AI validate LocationIQ tool outputs?

The framework inspects the JSON responses from tools like search and directions against defined schemas. If LocationIQ returns an unexpected field or missing coordinate, Pydantic AI raises a validation error immediately.

Q: How do I configure the LocationIQ MCP toolset in Pydantic AI?

You initialize the MCPToolset with the HTTP endpoint of your hosted server and pass it to the agent. This unified approach replaces the deprecated HTTP client classes for cleaner code.

Bring strict type safety to your spatial agents with Pydantic AI and the LocationIQ MCP server.

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 Pydantic AI

Create your Vinkius account to connect LocationIQ to Pydantic AI 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 Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-safe search with Pydantic AI

The `search` tool converts text queries into validated geographic coordinates, ensuring your Pydantic AI agent never processes malformed spatial data. The framework enforces strict schemas on the returned latitude and longitude, throwing immediate validation errors if the API payload deviates. When users type partial queries, the `autocomplete` tool provides real-time address suggestions that conform to strict Python models. This prevents your Pydantic AI agent from hallucinating coordinates or passing broken strings to downstream logistics systems.

Validated routing and reverse geocoding

The `directions` tool calculates routing paths and travel durations, returning structured JSON that matches your Pydantic AI models. If the routing geometry contains unexpected fields, the framework catches the error immediately, protecting your backend from silent failures. For mobile tracking, the `reverse` tool converts raw GPS coordinates into structured street addresses. Because every field is validated at runtime, you can write clean Python code knowing the address components are always typed correctly.

Structured map generation and timezone checks

The `static_map` tool generates visual map URLs for specific coordinates, returning a validated string format. Your Pydantic AI agent can safely pass this URL to frontend components, confident that the string is a properly formatted web link. The `timezone` tool resolves local times and offsets, while the `nearby` tool finds points of interest around coordinates. These tools run through a unified MCP toolset integration, keeping your spatial logic clean, modular, and fully typed.

Setup guide

Set up LocationIQ MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "locationiq-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to LocationIQ tools.",
)

result = await agent.run("List recent LocationIQ transactions")
print(result.output)

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 Pydantic AI

The framework inspects the JSON responses from tools like `search` and `directions` against defined schemas. If LocationIQ returns an unexpected field or missing coordinate, Pydantic AI raises a validation error immediately.

Yes, because Pydantic AI is model-agnostic, you can connect this server to local models or commercial APIs. The model simply calls the tools, while the framework handles the schema validation.

You initialize the `MCPToolset` with the HTTP endpoint of your hosted server and pass it to the agent. This unified approach replaces the deprecated HTTP client classes for cleaner code.

The framework catches the network error or API failure and raises a standard Python exception. Your Pydantic AI agent can catch this exception to trigger fallbacks, such as retrying the geocoding request.

Your geocoding queries, coordinates, and route requests are sent directly to the API through a secure V8 sandbox. This setup ensures that sensitive address data is never stored locally or exposed to unauthorized networks.

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