How to Use the CountryStateCity MCP in Pydantic AI

Q: How do I initialize CountryStateCity in Pydantic AI using MCP?

Install pydantic-ai-slimmcp, instantiate MCPToolset with your Vinkius endpoint URL, and pass it to your Agent in the toolsets list. This gives your agent type-safe access to all country and state tools.

Q: Does the CountryStateCity MCP Server support SSE transport in Pydantic AI?

Yes, the MCPToolset supports both Streamable HTTP and SSE transports. You can choose the transport method that matches your deployment architecture, keeping your geographic lookups fast and reliable.

Run type-safe geographic queries with Pydantic AI and this MCP Server to catch invalid ISO codes at runtime.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect CountryStateCity MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-Safe ISO Validation with Pydantic AI

`get_country` and `get_state` return structured geographic data that Pydantic AI validates against strict schemas before your agent even sees it. If the server returns unexpected metadata, the SDK raises a validation error immediately rather than letting bad data corrupt your database. You initialize this by loading `MCPToolset` with your Vinkius HTTP URL and passing it to your `Agent` via `toolsets`. This unified pattern replaces deprecated HTTP classes and guarantees that your agent's inputs and outputs match your exact type definitions.

Strict City Resolution via MCP Server

`list_cities_by_state` and `list_cities_by_country` supply raw city lists that your agent parses into type-safe Python models. Because the framework is model-agnostic, you can use this geographic validation with OpenAI, Anthropic, or local models. Note that retrieving cities by country requires the Supporter+ tier. Your agent handles this constraint programmatically, falling back to state-level lookups if the country-level tool returns an auth error.

Prevent Hallucinations in Global Lists

`list_countries` and `list_states` give your agent an immutable list of real-world entities to validate user input against. The agent cannot invent fake countries because the Pydantic validator forces it to match the exact string outputs returned by the server. This strict runtime enforcement makes the setup ideal for financial or medical applications where shipping or compliance locations must be 100% accurate. You get absolute correctness over silent, unpredictable model failures.

Setup guide

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

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

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

Install `pydantic-ai-slim[mcp]`, instantiate `MCPToolset` with your Vinkius endpoint URL, and pass it to your `Agent` in the `toolsets` list. This gives your agent type-safe access to all country and state tools.

The framework raises a validation error immediately at runtime instead of passing the corrupted data to your model. This loud failure prevents downstream database corruption and lets you debug the issue instantly.

Yes, the `MCPToolset` supports both Streamable HTTP and SSE transports. You can choose the transport method that matches your deployment architecture, keeping your geographic lookups fast and reliable.

Yes, because Pydantic AI is model-agnostic, you can connect the geography toolset to local Ollama or Llama.cpp instances. The framework validates the local model's tool calls against the server's schema just like it would with a commercial API.

Your requests to query countries, states, and cities are encrypted in transit via HTTPS to Vinkius. The server runs in a sandboxed V8 isolate that immediately discards your query parameters once the geographic payload is returned.

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