How to Use the Affinda MCP in Pydantic AI

Q: How do I initialize Affinda with Pydantic AI?

Install pydantic-ai-slimmcp. Create an MCPToolset instance with your Vinkius HTTP URL and add it to the toolsets list when defining your Agent.

Q: Does Pydantic AI validate the JSON from Affinda?

The framework automatically checks the output of getdocument against the MCP tool schema. You can also define custom response models to strictly validate the final extracted data.

Build type-safe document extraction agents by connecting Affinda to Pydantic AI for strict runtime validation.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Affinda MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Enforce Strict Types on Affinda Extraction

The `get_document` tool retrieves the structured JSON from your parsed files so Pydantic AI can validate every single field against your defined models. If Affinda returns an unexpected date format on an invoice, the framework fails loudly instead of passing bad data. Sending files works exactly the same way. Your agent invokes `create_document` with a public URL, and the synchronous response must match the expected schema before the agent takes its next step.

Discover Supported Models via MCP Server

Agents query `list_document_types` to see exactly which parsing models your account supports. This prevents the system from attempting to parse a custom form when only standard resumes are enabled. You initialize this connection using `MCPToolset` with your Vinkius HTTP endpoint. The framework handles the transport while keeping the external server execution entirely separate from your application logic.

Monitor Workspaces with Type Safety

Pulling directory structures requires the `list_workspaces` tool. The agent gets a clear map of all document containers, and Pydantic ensures the workspace IDs match your expected UUID formats. Tracking progress happens through the `list_documents` tool. Your agent polls the processing status of multiple files, relying on strict validation to confirm whether a document is actually complete or just queued.

Setup guide

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

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

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

Install `pydantic-ai-slim[mcp]`. Create an `MCPToolset` instance with your Vinkius HTTP URL and add it to the `toolsets` list when defining your Agent.

The framework automatically checks the output of `get_document` against the MCP tool schema. You can also define custom response models to strictly validate the final extracted data.

The framework is completely model-agnostic. You can route the Affinda tool outputs to OpenAI, Anthropic, or a local model running on your machine.

The framework fails loudly if the tool receives invalid inputs or unexpected outputs. Check your Pydantic validation logs to see which required field was missing from the extraction.

Authentication requires only a single endpoint token. The document URLs and extracted personal details flow through an ephemeral sandbox that leaves no trace on our servers after execution.

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