How to Use the Planhat MCP in Pydantic AI

Q: How does the Planhat MCP server work with Pydantic AI?

After you pip install "pydantic-ai-slimmcp", just instantiate the MCPToolset with your Vinkius URL. Pydantic AI handles the tool discovery and, more importantly, validates every single API response against the tool's output schema.

Q: How do I check for inactive users in Planhat with my Pydantic AI agent?

Instruct your agent to call the listplanhatendusers tool. Pydantic AI guarantees that the response is a correctly structured list of user objects before your agent's code can touch it, which makes filtering and analysis straightforward.

Q: How does this server handle sensitive note and conversation data from Planhat?

Data from tools like listplanhatnotes and listplanhatconversations is processed in a Vinkius-managed sandbox. The environment is completely isolated and ephemeral. It's created just for your request and is permanently deleted the moment it's complete, ensuring your data is never logged or stored.

Get validated Planhat data you can actually trust. This server lets your Pydantic AI agent work with customer data that's guaranteed to be type-safe.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers — Included with Plan

Connect Planhat MCP to Pydantic AI

Create your Vinkius account to connect Planhat to Pydantic AI — we handle the hosting, security, and runtime updates so you don't have to. No server setup required.

GDPR Included with Plan

Setup Planhat with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity Vinkius runs on Gemini

Gemini

Grok

Get Type-Safe Company Records

When your agent calls `get_planhat_company`, Pydantic AI forces the response into a strict data model before your code ever sees it. This is the whole point. You get the data you expect, every time. If Planhat's API ever sends back a null value where you expect a string, your agent fails with a loud `ValidationError`. No more silent data corruption. No more debugging bizarre agent behavior caused by bad upstream data.

Reliably Track Customer Tasks

Build operational workflows that don't break. Your agent can call `list_planhat_tasks` to see every open item for an account, and Pydantic AI validates each task object in the response list. Because every field is checked at runtime, you can trust the reports and summaries your agent generates. This lets you build dependable automations on top of Planhat data, regardless of which LLM you use as the brain.

A Correctness-First Planhat MCP Server

This approach protects your agent from any unexpected API changes. Whether you're pulling user lists with `list_planhat_end_users` or license details with `list_planhat_licenses`, Pydantic AI acts as a runtime guard. It ensures the data your agent reasons about perfectly matches the schema you defined. This MCP server delivers clean, predictable data structures so you can focus on your agent's logic, not on data cleaning.

Setup guide

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

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

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

After you `pip install "pydantic-ai-slim[mcp]"`, just instantiate the `MCPToolset` with your Vinkius URL. Pydantic AI handles the tool discovery and, more importantly, validates every single API response against the tool's output schema.

Yes, that's exactly what this is for. When your agent uses tools like `list_planhat_projects`, the runtime validation means you can build workflows that don't fail silently. You're protected from unexpected API changes or malformed data.

Instruct your agent to call the `list_planhat_end_users` tool. Pydantic AI guarantees that the response is a correctly structured list of user objects before your agent's code can touch it, which makes filtering and analysis straightforward.

It solves a different problem. This gives your AI agent a structured, validated way to interact with the Planhat API. You don't have to write the boilerplate for auth, API calls, or—most importantly—the runtime data validation yourself.

Data from tools like `list_planhat_notes` and `list_planhat_conversations` is processed in a Vinkius-managed sandbox. The environment is completely isolated and ephemeral. It's created just for your request and is permanently deleted the moment it's complete, ensuring your data is never logged or stored.

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