How to Use the Factorial MCP in Pydantic AI

Q: How do I connect Pydantic AI to Factorial?

Install the pydantic-ai-slim package and use the MCPToolset to point to the server URL. It integrates directly into your agent's toolsets list.

Use Pydantic AI for type-safe interaction with the Factorial MCP server, ensuring reliable HR data validation in your code.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Factorial MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-safe HR data in Pydantic AI

Every response from Factorial is validated against your Pydantic models. Use `get_employee` or `list_teams` and know exactly what data format your agent is handling. If the API schema shifts, your agent catches the error immediately. This prevents the silent data corruption that happens when agents guess at JSON structures.

Reliable payroll and document queries

Call `list_payslips` to get financial data that fits your defined schemas. Your agent handles the output with strict validation, ensuring payroll figures are parsed correctly every time. This is for when you need precision. By using Pydantic AI, you lock down the data flow from Factorial so your agent only acts on verified, expected information.

Precise leave and shift tracking

Fetch shift data using `list_shifts` and validate it against your internal models. Your agent reads the output and confirms it matches your expected format before proceeding. It turns raw API output into reliable application state. You spend less time debugging data issues and more time building your agent's logic.

Setup guide

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

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

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

It forces runtime validation on every response. You get a failure if the data doesn't match your Pydantic model, preventing your agent from hallucinating or crashing on bad data.

Install the pydantic-ai-slim package and use the `MCPToolset` to point to the server URL. It integrates directly into your agent's toolsets list.

The framework handles the underlying protocol. You just define your models, and the toolset takes care of the mapping and validation for the Factorial endpoints.

Yes, the framework is model-agnostic. You can switch between different LLMs while keeping your Factorial tool definitions and Pydantic validation logic consistent.

The server enforces access through your API token. Since your agent only receives data that passes your Pydantic model validation, you effectively filter and sanitize all incoming information.

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