How to Use the folk MCP in Pydantic AI

Q: What happens if the folk API changes and Pydantic AI finds an error?

Your agent will raise a ValidationError. This is the key benefit—it fails loudly instead of passing bad data through your system. You'll know instantly that the data from listcontacts doesn't match your expected schema.

Q: How do I set up the folk MCP server with Pydantic AI?

It's one line of code: toolset = MCPToolset("http://..."). Then you pass that toolset to your Agent's constructor. Pydantic AI handles all the tool discovery and model generation.

Q: Does this work with async Python code for folk and Pydantic AI?

Yes, it's designed for async. All the tool calls, like getcontactdetails or listinteractions, are awaitable. This lets you build responsive agents that can handle multiple tasks at once without blocking.

Q: Can I use Pydantic AI to build a script that cleans up my folk contacts?

It's a perfect fit. You can write an agent that uses listcontacts to fetch all records, then applies custom validation logic using your own Pydantic models. If a contact is missing a key field, the agent can flag it or attempt to fix it.

Manage your folk CRM with type-safe, validated agents that never fail silently, powered by Pydantic AI.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect folk MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Correctness By Default

Pydantic AI forces correctness. When your agent calls `get_contact_details`, the response is automatically parsed and validated against a strict Pydantic model. If the folk API ever returns an unexpected field or a missing email, your code will raise an error immediately. This means no more silent data corruption. You can trust that every contact object your agent works with is exactly what you expect it to be. It's the right way to build reliable automations on top of your CRM data.

Model-Agnostic CRM Agents

Pydantic AI doesn't care if you're using OpenAI, Gemini, or a local model. The logic for interacting with folk is completely separate from the LLM. You define the tools, like `create_contact` and `list_contacts`, and they work everywhere. This lets you swap out LLMs without rewriting your CRM integration code. You can test a new model tomorrow and be confident your agent can still pull `list_contact_notes` and manage your groups perfectly.

The Pydantic AI Toolset for this MCP Server

Connecting this MCP server is dead simple. Just instantiate the `MCPToolset` with the server URL. Pydantic AI handles the rest, fetching the tool schemas and generating the necessary models on the fly. Your agent code becomes cleaner. Instead of writing HTTP requests and parsing JSON, you're just calling functions. It feels like working with a native Python library for folk, but it's powered by an LLM.

Setup guide

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

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

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

Your agent will raise a `ValidationError`. This is the key benefit—it fails loudly instead of passing bad data through your system. You'll know instantly that the data from `list_contacts` doesn't match your expected schema.

It's one line of code: `toolset = MCPToolset("http://...")`. Then you pass that toolset to your `Agent`'s constructor. Pydantic AI handles all the tool discovery and model generation.

Yes, it's designed for async. All the tool calls, like `get_contact_details` or `list_interactions`, are awaitable. This lets you build responsive agents that can handle multiple tasks at once without blocking.

It's a perfect fit. You can write an agent that uses `list_contacts` to fetch all records, then applies custom validation logic using your own Pydantic models. If a contact is missing a key field, the agent can flag it or attempt to fix it.

We treat your data like it's radioactive. The server processes your requests for contact details, notes, and group lists in a zero-trust, ephemeral environment. Nothing is logged or stored; we just proxy the request to folk.

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