How to Use the Home Assistant MCP in Pydantic AI

Q: How does Pydantic AI ensure my agent calls Home Assistant services correctly?

Pydantic AI validates the data your agent sends with callhaservice and, more importantly, validates the response from Home Assistant. If the API returns anything unexpected, your agent gets a ValidationError instead of bad data, so you always know if a command actually succeeded.

Q: What happens if Home Assistant returns bad data to my Pydantic AI agent?

Your agent's code won't crash with a NoneType error. Instead, Pydantic AI will raise a ValidationError immediately, telling you exactly which field was missing or had the wrong type. This prevents silent failures in your automations.

Build type-safe Home Assistant agents that won't fail silently, powered by Pydantic AI's 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 Home Assistant MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Get Validated State Data. Guaranteed.

Stop guessing what the API will return. When your agent calls `get_entity_state` or `list_entity_states`, Pydantic AI automatically validates the response against a model. If Home Assistant ever sends back a malformed object or an attribute with the wrong data type, you get a clean `ValidationError`, not a cryptic runtime bug. This means you can write code that trusts the data it receives. You know for a fact the `temperature` from a `climate` entity is a number and the `state` of a `light` is a string. No more defensive coding just to handle bad API responses.

Execute Commands with Confidence

Pydantic AI brings type safety to `call_ha_service`. You can define a Pydantic model for the `service_data` your agent intends to send, ensuring the structure is correct before the API call is ever made. It's a simple way to prevent entire classes of errors. The real value is in the response. If a service call fails or returns an error, Pydantic AI ensures your agent knows about it. This is the difference between an agent that *thinks* it closed the garage door and one that *knows* it did because it received a validated success response.

Your Pydantic AI Agent, Your LLM

This MCP Server works with any LLM that Pydantic AI supports. You aren't locked into a single provider. Point your agent to the server endpoint and use it with an agent powered by OpenAI, Anthropic, Gemini, or a local model running on your own machine. The tools just work because the validation layer is model-agnostic. It sits between the LLM and your Home Assistant instance. No matter which model generates the tool call for `render_ha_template` or `get_calendar_events`, Pydantic AI ensures the call is valid and the response is clean before your code sees it.

Setup guide

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

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

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

Pydantic AI validates the data your agent sends with `call_ha_service` and, more importantly, validates the response from Home Assistant. If the API returns anything unexpected, your agent gets a `ValidationError` instead of bad data, so you always know if a command actually succeeded.

Yes. Pydantic AI is model-agnostic. You can run your agent with a local model (like Llama or Mistral) and connect it to this MCP server to interact with your Home Assistant instance, all while benefiting from Pydantic's runtime validation.

Your agent's code won't crash with a `NoneType` error. Instead, Pydantic AI will raise a `ValidationError` immediately, telling you exactly which field was missing or had the wrong type. This prevents silent failures in your automations.

It's not about raw speed, it's about development time and correctness. You get 15 pre-built, tested tools with runtime validation out of the box. You'll have a robust agent running in minutes instead of spending hours writing and debugging an API client.

The server only requests the data your agent asks for, such as entity states via `get_entity_state` or configuration details from `get_ha_config`. Vinkius runs your MCP server instance inside a V8 Isolate sandbox, which provides a secure, single-tenant environment for your requests.

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