How to Use the Geocode.xyz MCP in Pydantic AI

Q: How do I configure Geocode.xyz for Pydantic AI?

Run pip install "pydantic-ai-slimmcp". Create an MCPToolset pointing to your Vinkius HTTP endpoint. Pass that toolset array to your Agent constructor.

Type-safe geocoding and location parsing for Pydantic AI agents.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Geocode.xyz MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Strict Geocoding for Pydantic AI

The `forward_geocode` tool converts a place name or address into geographic coordinates. Pydantic AI demands strict schemas for every tool call. When your agent requests coordinates, the framework validates the latitude and longitude response at runtime. If the API returns an unexpected string instead of a float, the agent fails loudly. You get a clear validation error instead of silent data corruption. This strictness ensures your downstream database only receives perfectly formatted spatial records.

Validate User Address Input

The `autocomplete` tool provides suggestions for partial street names, postal codes, or city names. Building a CLI tool requires handling messy user input. Your agent takes the broken address, hits this tool, and receives an array of valid corrections. Because Pydantic AI is model-agnostic, you can swap between Anthropic, OpenAI, or local models without rewriting this logic. The MCP Server standardizes the connection. The agent simply reads the validated suggestions and prompts the user to confirm the right one.

Translate Coordinates Safely

The `reverse_geocode` tool translates latitude and longitude coordinates back into physical addresses. Your application might track delivery drivers via GPS. The agent takes those raw coordinates and figures out exactly what street the driver is on. You configure this by passing `MCPToolset` to your agent. The framework handles the asynchronous HTTP transport automatically. The agent waits for the exact street address, validates the response model, and continues its workflow.

Setup guide

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

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

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

Run `pip install "pydantic-ai-slim[mcp]"`. Create an `MCPToolset` pointing to your Vinkius HTTP endpoint. Pass that toolset array to your Agent constructor.

Yes. Every response from the tool must match the expected Pydantic model. If the geocoding data is malformed, the framework throws a validation error immediately.

Yes. Pydantic AI is completely model-agnostic. As long as your local model supports function calling, it can interact with this server just like a commercial model.

The framework stops execution. You will not get silent failures or hallucinated fields. The agent catches the type mismatch and alerts you to the exact problem.

Your data stays private through ephemeral processing. When you send IP addresses for geolocation, the V8 isolate handles the request and immediately discards the tokens. No logs retain your network data.

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