How to Use the Holiday API MCP in Pydantic AI

Q: How do I check which countries are supported before running a query?

Call the listsupportedcountries tool at the start of your workflow. Your agent can use this array to validate user input before attempting to retrieve regional holiday schedules.

Run type-safe holiday checks with Pydantic AI to guarantee your automated payroll never miscalculates international overtime.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Holiday API MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Validate calendar math using Pydantic AI and MCP Server

The `get_workdays_count` tool returns validated integer counts of active operational days between two dates. Because this framework enforces strict runtime validation, any unexpected API response triggers an immediate validation error instead of silently passing corrupt data to your backend. This type safety is essential when calculating payroll for thousands of employees globally. You can trust that the days returned correspond exactly to real-world calendar parameters without risking compliance violations.

Calculate precise operational resumes

Computing the exact date business resumes after a specified duration is handled by the `get_next_workday` tool. Your model-agnostic agents can use this to schedule automated follow-ups or invoice generation. By wrapping this MCP Server in a unified MCPToolset, your agent gains direct access to precise date math. The tool handles the complex timezone and calendar logic, leaving your agent to focus on the business workflow.

Audit international closures programmatically

To pull the complete list of public closures for any supported country and year, use the `get_holidays` tool. Your agent can cross-reference these dates against shift schedules to flag potential staffing shortages. Using `list_supported_countries` and `list_supported_languages` ensures your agent knows exactly which regions and locales are valid before making a request. This proactive verification prevents runtime failures during batch processing runs.

Setup guide

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

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

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

Use the unified MCPToolset class with your Vinkius HTTP endpoint. Pass this toolset directly into your Agent's toolsets list to expose tools like `get_holidays` to your model.

Yes, because this MCP framework is model-agnostic, you can use this server with OpenAI, Anthropic, or local models. The validation layer ensures the returned holiday dates match your schema regardless of the LLM used.

If the MCP Server returns an unexpected structure, the framework raises a validation error. This prevents your agent from parsing corrupted date formats or hallucinated holiday names, keeping your database clean.

Call the `list_supported_countries` tool at the start of your workflow. Your agent can use this array to validate user input before attempting to retrieve regional holiday schedules.

The server only receives anonymous parameters like ISO country codes, years, and start/end dates. No employee names, salary details, or sensitive company files are ever transmitted, ensuring your payroll data remains secure.

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