How to Use the HubSpot Analytics MCP in Pydantic AI

Q: How do I initialize the HubSpot Analytics MCP Server in Pydantic AI?

Install the slim package with MCP support and use the MCPToolset class pointing to your Vinkius HTTP endpoint. Pass this toolset instance inside the toolsets list when instantiating your Pydantic AI agent. The agent then gains access to all five analytics tools.

Q: Can I use Pydantic AI to filter HubSpot Analytics views dynamically?

Yes, your agent can call hsanalyticsviews to discover the available reporting scopes. It then uses the validated view ID to filter subsequent queries to hswebanalytics. Every step of this discovery process is fully typed.

Build type-safe HubSpot workflows with runtime validation using 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 Analytics MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Validate web analytics inside Pydantic AI

`hs_web_analytics` gets traffic metrics like sessions, new contacts, and bounce rates directly into your type-safe agent. The tool maps these incoming HubSpot fields to strict Python types at runtime. Pydantic AI ensures that if HubSpot returns an unexpected data format, your application fails immediately instead of passing corrupted metrics to your model. This prevents your agent from hallucinating traffic trends or making decisions on bad numbers.

Audit email campaign metrics with this MCP Server

`hs_email_analytics` pulls exact open rates, click counts, bounces, and spam reports into your validation pipeline. This MCP Server tool enforces strict schema checks on every single email marketing metric returned by the API. Pydantic AI validates these delivery statistics before your agent can use them to draft reports. You get absolute certainty that your automated email audits are running on verified, well-formed data.

Track contact timelines with absolute type-safety

`hs_list_events` fetches page views, form submissions, and meetings for specific contacts, companies, or deals. The tool requires a validated object type and ID to pull this timeline data. The Pydantic AI framework validates the structure of these CRM events before your agent processes them. This prevents silent failures when parsing complex interaction histories from your HubSpot portal.

Setup guide

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

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

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

Install the slim package with MCP support and use the `MCPToolset` class pointing to your Vinkius HTTP endpoint. Pass this toolset instance inside the `toolsets` list when instantiating your Pydantic AI agent. The agent then gains access to all five analytics tools.

Pydantic AI will raise a validation error at runtime if the response does not match the expected schema. This prevents your agent from processing malformed data from tools like `hs_analytics_views` or `hs_list_reports`. It keeps your production system clean.

Yes, Vinkius hosts and runs the server externally for you. Your Pydantic AI agent connects to the hosted endpoint via Streamable HTTP or SSE. You do not need to manage local Node or Python runtimes to use these tools.

Yes, your agent can call `hs_analytics_views` to discover the available reporting scopes. It then uses the validated view ID to filter subsequent queries to `hs_web_analytics`. Every step of this discovery process is fully typed.

Every request to list custom reports or fetch traffic data goes through a temporary V8 sandbox execution environment. Pydantic AI processes the validated JSON payloads in-memory, ensuring your credentials and metrics are never written to disk.

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