How to Use the HubSpot MCP in Pydantic AI

Q: How do I connect HubSpot to Pydantic AI?

Install pydantic-ai-slimmcp and initialize MCPToolset with your Vinkius HTTP endpoint. Pass the configured toolset to your Agent constructor to expose the CRM tools.

Q: Can I use local models with the HubSpot MCP Server?

Yes. Pydantic AI is completely model-agnostic. You run listhubspotusers or listcompanies using an open-source model, and the framework still enforces your type constraints.

Q: Is the old HTTP server method supported for Pydantic AI?

The MCPServerHTTP class is deprecated. You must use the unified MCPToolset approach to connect to the external Vinkius endpoint.

Bring strict type safety to your HubSpot CRM data by validating every MCP Server response with 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 HubSpot MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Enforce schema correctness via Pydantic AI

When your Pydantic AI agent calls `get_contact_details`, the HubSpot MCP Server returns raw CRM data that gets validated instantly. The framework checks every returned field against your strict type hints. If the CRM spits out a string instead of an expected integer, the agent crashes loudly. You get a strict validation error. Silent data corruption doesn't happen here. Hallucinated properties won't ruin your database sync.

Manage deals with type-safe operations

Your agent reads the current sales pipeline using `list_deals` and `get_deal_details` while guaranteeing the output matches your expectations. Because Pydantic AI is model-agnostic, you swap between Anthropic and local models without rewriting your validation logic. Before creating new relationships, the agent checks the required properties via `get_object_schema`. It then executes `link_crm_objects` to tie the deal to a company, knowing the input parameters perfectly match the CRM requirements.

Build reliable contact workflows with MCP

This MCP server provides the exact primitives needed to manage customer records, starting with `create_contact` and `list_contacts`. You define the exact shape of a valid contact in Python, and the framework ensures the agent strictly adheres to it. When an agent needs to clean up the database, it uses `search_contacts` to find obsolete entries and `remove_contact` to delete them. The unified `MCPToolset` setup keeps the connection stable, so your agent focuses entirely on executing correct operations.

Setup guide

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

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

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

Install `pydantic-ai-slim[mcp]` and initialize `MCPToolset` with your Vinkius HTTP endpoint. Pass the configured toolset to your Agent constructor to expose the CRM tools.

The framework throws a strict validation error at runtime. If `get_company_info` returns a missing required field, the agent catches it immediately instead of passing bad data downstream.

Yes. Pydantic AI is completely model-agnostic. You run `list_hubspot_users` or `list_companies` using an open-source model, and the framework still enforces your type constraints.

The `MCPServerHTTP` class is deprecated. You must use the unified `MCPToolset` approach to connect to the external Vinkius endpoint.

The server transmits user IDs, phone numbers, and pipeline stages over a secure, stateless connection. Vinkius manages the authentication layer externally, meaning your local Python environment never stores raw CRM credentials.

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