How to Use the UKG Pro MCP in Pydantic AI

Q: How does UKG Pro integrate with Pydantic AI?

The MCP Server exposes employees, jobs, organizations, and payroll. The Pydantic framework acts as a runtime validator, ensuring that every single piece of data pulled from UKG Pro matches the expected Python structure.

Q: What happens if I query organizational structures using UKG Pro and Pydantic AI?

You invoke organizations. The Pydantic layer then validates the returned list structure, making sure that every component unit is formatted correctly for your agent to use.

Get guaranteed accurate HR reads from UKG Pro using the Pydantic AI framework.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect UKG Pro MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Check specific employee profiles.

Calling `employees` pulls an individual worker's record directly out of UKG Pro. Because you use the Pydantic AI, every field returned is validated against a strict schema at runtime. This means if the API sends unexpected data, your agent fails loudly with a specific validation error—no silent corruption.

Get job configuration details.

Need to check what a job code means? Use `jobs` for that. The Pydantic framework guarantees that the returned job configuration data adheres exactly to your expected Python types. This focus on correctness makes it reliable, whether you're using OpenAI or Anthropic models through this MCP Server.

Pull current payroll records.

The `payroll` tool pulls the full set of pay records for the active period. The Pydantic validation ensures that every single field—like salary amounts or dates—is present and typed correctly. This reliability is key when your agent needs to process financial data, as it catches malformed responses immediately.

Setup guide

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

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

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

The MCP Server exposes `employees`, `jobs`, `organizations`, and `payroll`. The Pydantic framework acts as a runtime validator, ensuring that every single piece of data pulled from UKG Pro matches the expected Python structure.

You invoke `organizations`. The Pydantic layer then validates the returned list structure, making sure that every component unit is formatted correctly for your agent to use.

Yes. Reliability is its whole point. If the underlying API changes and returns unexpected fields, the Pydantic AI immediately throws an error instead of letting your agent process bad data.

It does. You can chain calls—say, getting an employee ID via `employees` and then using that ID to pull payroll records via `payroll`. The validation keeps everything clean.

This server handles sensitive HR data, including specific worker profiles (from `employees` and `payroll`) and organizational structures. You are dealing with PII and compensation metrics.

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