How to Use the TimezoneDB MCP in Pydantic AI

Q: How do I configure TimezoneDB with Pydantic AI?

Install the pydantic-ai-slimmcp package. Initialize an MCPToolset with your Vinkius URL and add it to your agent's configuration.

Q: Which transport layer should I use for TimezoneDB in Pydantic AI?

The unified MCPToolset supports both Streamable HTTP and SSE transports. Pick the one that matches your Vinkius deployment.

Type-safe time operations for Pydantic AI. Validate every timezone and coordinate before your agent acts.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers — Included with Plan

Connect TimezoneDB MCP to Pydantic AI

Create your Vinkius account to connect TimezoneDB to Pydantic AI — we handle the hosting, security, and runtime updates so you don't have to. No server setup required.

GDPR Included with Plan

Setup TimezoneDB with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity Vinkius runs on Gemini

Gemini

Grok

Type-safe TimezoneDB MCP Server integration

Silent failures in time calculations ruin production databases. Pydantic AI forces every response from your external tools to match strict schemas. You connect this by passing `MCPToolset` with your HTTP endpoint into your agent's `toolsets` array. When your model requests the current time for a specific region, it triggers `get_time_by_zone`. If the API returns a malformed string or unexpected offset, Pydantic throws a validation error immediately.

Audit coordinates and shifts

Mapping physical locations to clocks requires precision. Your agent uses `get_time_by_location` to transform raw latitude and longitude floats into validated local timestamps. It also checks the current rules for clock changes. Calling `get_dst_status` returns a strict boolean indicating if summer time is active, ensuring your agent never hallucinates an hour difference.

Discoverable time directories

Building dropdowns or validating user input often requires a complete reference list. The agent can execute `list_timezones` to grab the entire directory of supported regions, optionally filtering by country code. Before running a critical scheduling loop, the system can run `check_api_status`. This confirms the upstream provider is healthy, preventing your agent from hanging on dead requests.

Setup guide

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

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

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

Install the `pydantic-ai-slim[mcp]` package. Initialize an `MCPToolset` with your Vinkius URL and add it to your agent's configuration.

Yes. Every piece of data returned by the server is checked against Pydantic models at runtime. Bad data causes a loud failure instead of silent corruption.

The unified `MCPToolset` supports both Streamable HTTP and SSE transports. Pick the one that matches your Vinkius deployment.

Yes. The framework is completely model-agnostic. As long as your local model supports tool calling, it can interact with the time server.

The server processes latitude, longitude, and region strings strictly for time calculation. Vinkius handles the authorization layer and runs the code in an ephemeral environment that retains zero state after execution.

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