How to Use the Geoapify MCP in Pydantic AI

Q: What's the advantage of Pydantic AI for Geoapify tools like routeplanner?

The routeplanner tool returns a complex JSON object. Pydantic AI gives you peace of mind by guaranteeing that the nested structure, data types, and required fields of that response are 100% correct before your code attempts to process it.

Q: How is my data, like addresses sent to geocodesearch, protected when using Geoapify and Pydantic AI?

Any data you send, including addresses for geocodesearch or GeoJSON for geometryoperation, is processed inside a Vinkius ephemeral instance. The container is created for your request and completely destroyed afterward, leaving no data behind.

Add type-safe, validated location intelligence to any Python agent using Geoapify and Pydantic AI.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Geoapify MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Geocoding That Won't Silently Fail

Location APIs often return messy data. Pydantic AI fixes that. When your agent calls Geoapify's `geocode_search` or `geocode_autocomplete`, the JSON response is automatically parsed and validated against a Pydantic model. If the API returns an unexpected structure, your code raises a `ValidationError` on the spot. This lets you build tool chains that don't break. The validated output from `geocode_search` is guaranteed to be clean input for `get_place_details`. No more hunting for `KeyError` exceptions in production because an optional field was missing. You get correctness by default.

Model-Agnostic Logistics with Pydantic AI

It doesn't matter if you're using GPT-4, Gemini, or a local model—Pydantic AI makes your agent's interaction with Geoapify consistent and safe. Use `calculate_route_matrix` to get travel times, and the framework ensures the result is a clean, nested list of floats, just like your code expects. This is essential for complex tools like `route_planner`, which returns a detailed object with stop ordering and route geometry. Pydantic AI validates that entire structure before your code ever sees it, which stops your agent from misinterpreting the results or hallucinating a bad route.

Validate Complex GeoJSON Responses

Geospatial data is notoriously tricky. When you ask this MCP server to run a `geometry_operation` or find a delivery area with `calculate_isoline`, it returns GeoJSON. Pydantic AI, paired with a GeoJSON model library, validates that the output is a structurally correct polygon or point collection. This means your agent can reliably work with geographic boundaries from this MCP server. It can call `get_boundaries_consists_of` to get all the districts in a city, and you know the result will be a valid list of polygons you can actually use. It's about building robust systems, not just prototypes.

Setup guide

Set up Geoapify 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": {
        "geoapify-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

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

result = await agent.run("List recent Geoapify 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 Geoapify. 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 Geoapify 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 Geoapify MCP in Pydantic AI

Pydantic AI automatically validates every API response from the Geoapify MCP server against a corresponding Pydantic model. If the data structure or types don't match what's expected, it raises an error immediately instead of passing bad data to your application.

Yes. Pydantic AI is model-agnostic. You can use it with any LLM, including local models run with Ollama or llama.cpp, to call the Geoapify tools in a structured, type-safe way.

The `route_planner` tool returns a complex JSON object. Pydantic AI gives you peace of mind by guaranteeing that the nested structure, data types, and required fields of that response are 100% correct before your code attempts to process it.

No, it's straightforward. You install the library, create an `MCPToolset` instance pointing to the Vinkius server URL, and pass it to your `Agent`. Pydantic AI handles the rest.

Any data you send, including addresses for `geocode_search` or GeoJSON for `geometry_operation`, is processed inside a Vinkius ephemeral instance. The container is created for your request and completely destroyed afterward, leaving no data behind.

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