How to Use the Finch MCP in Pydantic AI

Q: How do I register the Finch MCP server in Pydantic AI?

You use the MCPToolset class and pass the HTTP endpoint of the server. This registers all eleven tools, including listdirectory and getemployment, making them available for runtime type validation.

Q: What happens if Finch returns unexpected data to Pydantic AI?

The framework will raise a ValidationError at runtime. This ensures that if an HRIS provider changes its schema, your agent fails loudly and safely instead of passing corrupt payroll or employee records into your system.

Q: Does this server support checking connection permissions?

Yes, you can call introspect to verify the scopes and permissions of your current connection, or use getme to check the status of the authorized application before running any data queries.

Q: How are sensitive salaries and tax details secured?

Your salary data and tax information fetched via getemployment are processed entirely in-memory within ephemeral, zero-trust MCP sandboxes. Vinkius manages the authentication tokens securely and never logs the contents of your HRIS payloads.

Build type-safe HR agents with Pydantic AI using this MCP Server to validate payroll and employee data 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 Finch MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-Safe Employee Directory Queries

Legacy HRIS systems return messy, unpredictable JSON. By using this MCP Server with Pydantic AI, every payload from `list_directory` and `get_individual` is validated against strict Python types before your agent ever sees it. If a provider returns a missing email field or an malformed phone number, the framework raises a validation error immediately. This prevents your downstream database insertions from failing due to dirty data.

Strict Payroll Validation with MCP Server

Handling financial data requires absolute precision. When your agent calls `list_pay_statements` or `list_pay_groups`, Pydantic AI enforces type checks on salary amounts, currency codes, and tax deductions to ensure no malformed data is processed. You define the schemas, and the framework guarantees the agent cannot output or act on hallucinated payroll figures. It is the safest way to automate compensation audits without human oversight.

Validate Employment Status Changes

Tracking job changes requires reliable state management. Your agent can query `get_employment` to pull an employee's title, salary, and department, validating that the returned object matches your internal database schema. If the agent needs to check sync status, it can call `get_automated_job` to ensure the background task completed successfully. Every step is fully typed, making your code easier to debug and maintain.

Setup guide

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

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

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

You use the `MCPToolset` class and pass the HTTP endpoint of the server. This registers all eleven tools, including `list_directory` and `get_employment`, making them available for runtime type validation.

The framework will raise a `ValidationError` at runtime. This ensures that if an HRIS provider changes its schema, your agent fails loudly and safely instead of passing corrupt payroll or employee records into your system.

Yes. You can define custom Pydantic models for the data returned by tools like `get_individual` or `list_pay_statements`. The framework will automatically parse and validate the JSON response against your models.

Yes, you can call `introspect` to verify the scopes and permissions of your current connection, or use `get_me` to check the status of the authorized application before running any data queries.

Your salary data and tax information fetched via `get_employment` are processed entirely in-memory within ephemeral, zero-trust MCP sandboxes. Vinkius manages the authentication tokens securely and never logs the contents of your HRIS payloads.

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