How to Use the FreeAgent MCP in Pydantic AI

Q: What happens if FreeAgent changes its API and my Pydantic AI agent breaks?

Your agent will raise a ValidationError on the first call that receives the new data structure. This is a core benefit—it fails loudly and immediately, preventing your agent from processing unexpected data from FreeAgent.

Q: How does Pydantic AI help when working with large lists from FreeAgent?

When your agent calls a tool like listinvoices, Pydantic AI will validate every single object in the returned list against your model. If even one invoice in a list of 100 has bad data, it will raise an error, pointing to the exact record that failed validation.

Build type-safe financial agents for FreeAgent. Pydantic AI validates every API response, so your agent never works with bad data.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect FreeAgent MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Get Invoice Data You Can Trust

Pull invoice details and know they're correct. When your agent calls `get_invoice_details`, Pydantic AI automatically parses the raw JSON response into a strict Pydantic model. If a field is missing or has the wrong type, you get an error instantly. This is a huge deal for financial data. It means your agent won't silently fail or proceed with corrupted information. If FreeAgent's API sends back something unexpected, your agent stops and tells you exactly what went wrong, preventing bad data from polluting your system.

Build Correct-by-Construction Logic

Track your expenses with absolute certainty. Your agent can pull data from both `list_purchase_bills` and `list_out_of_pocket_expenses`, with Pydantic AI ensuring both sets of data conform to the schemas you've defined. There's no guesswork involved. This lets you build financial logic that's reliable from the ground up. You can confidently sum totals, compare dates, and process records because you know the data structure is guaranteed. Your code becomes simpler because you don't have to write tons of defensive checks.

A Model-Agnostic MCP Toolset

This FreeAgent connection works with any LLM. Pydantic AI is model-agnostic, so you can use this MCP server with models from OpenAI, Anthropic, Google, or even a local one. The tools, like `get_company_details` and `list_bank_accounts`, are presented to the model in a standard way. All you do is instantiate the `MCPToolset` with your Vinkius server URL and add it to your agent. Pydantic AI handles the function calling, response parsing, and data validation, letting you focus on the agent's logic instead of the plumbing.

Setup guide

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

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

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

Your agent will raise a `ValidationError` on the first call that receives the new data structure. This is a core benefit—it fails loudly and immediately, preventing your agent from processing unexpected data from FreeAgent.

When your agent calls a tool like `list_invoices`, Pydantic AI will validate every single object in the returned list against your model. If even one invoice in a list of 100 has bad data, it will raise an error, pointing to the exact record that failed validation.

Pydantic AI is flexible. If your agent needs to follow complex instructions, a top-tier model like GPT-4 or Claude 3 Opus is a good choice. If the tasks are simple, like fetching a specific invoice, a smaller, faster model will work just fine.

This MCP server provides a managed, secure, and standardized way to access the API. Pydantic AI then adds a critical layer of type safety on top, saving you from writing boilerplate validation code and protecting your agent from data corruption.

The server processes sensitive FreeAgent data like invoices, bills, and P&L statements. Vinkius secures the connection with a private token and runs the server in an ephemeral sandbox. Pydantic AI adds its own security benefit: it acts as a data firewall, ensuring that only data that strictly matches your predefined schemas can ever reach your agent's logic.

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