Skip to main content

Configure HubSpot models with Claude

FunnelStory's MCP server lets you configure data models directly from a conversation with Claude. Instead of writing SQL queries and manually filling in mappings, you describe what you want and Claude reads your HubSpot schema, previews the data, and creates the models in the correct order.

This guide walks through configuring all standard HubSpot models — accounts, users, email conversations, notes, and behavioral events — using Claude.

Prerequisites​

  1. A HubSpot connection added in FunnelStory. See HubSpot.
  2. The FunnelStory MCP server connected to Claude. See MCP Getting Started.
  3. Your Claude user must have Admin role in your FunnelStory workspace — model configuration requires admin access.

Step 1: Check your workspace and connection​

Start by asking Claude to identify your current workspace and available data connections:

"Who am I in FunnelStory, and what data connections do I have?"

Claude calls who_am_i and read_resource("file://workspace/profile.json") to confirm your identity, workspace, and the HubSpot connection ID it will use for configuration.

Step 2: Configure the accounts model​

The accounts model is the foundation — everything else depends on it. Configure it first.

"Configure a HubSpot accounts model using deals and companies"

Claude will:

  1. Read file://data_model/guide.md for the correct query pattern.
  2. Call preview_data_model to validate the query returns rows with expected fields.
  3. Create the model with configure_data_model.

What it configures: An accounts model that builds your account list from HubSpot companies that have at least one associated deal. This ensures only active prospects and customers appear as FunnelStory accounts.

Deals-based accounts

FunnelStory uses deals — not just companies — as the source of truth for accounts. A company must have at least one deal to be included. This keeps your account list focused and prevents noise from all your HubSpot contacts' companies appearing as accounts.

Step 3: Configure the users model​

After accounts, configure users so FunnelStory can resolve contacts to accounts.

"Configure a HubSpot users model"

Claude creates a users model that:

  • Reads HubSpot contacts associated with deal companies
  • Matches contacts to accounts via email domain
  • Gives FunnelStory the contact→account mapping needed for email engagement resolution
Required before engagement models

Without the users model, FunnelStory cannot sync contacts from HubSpot. And without contacts, email conversation models cannot resolve which account an email belongs to. Always configure users before conversations or non-product activity models.

Step 4: Configure email conversations​

Once accounts and users are in place, configure HubSpot email conversations to bring your team's customer emails into the account timeline with sentiment analysis.

"Configure a HubSpot email conversation model"

Claude creates a conversation model that:

  • Queries HubSpot incoming and outgoing emails (INCOMING_EMAIL, EMAIL)
  • Resolves account_id by matching the sender email to a known contact via contacts_v2
  • Passes email body text through FunnelStory's AI analysis pipeline for sentiment scoring, text analysis, and label analysis
  • Shows the email subject as the timeline entry title with a link to HubSpot

Step 5: Configure notes​

HubSpot notes are often the richest source of qualitative account information — notes from calls, onboarding sessions, and customer feedback. Configure them as a Note model (not a Conversation) to make them appear on the dedicated Notes page and generate needle movers.

"Configure a HubSpot notes model"

Claude creates a note model that:

  • Queries HubSpot notes (NOTE) scoped to your synced companies
  • Resolves account_id via the HubSpot engagement → company associations
  • Makes notes searchable and surfaced in AI-driven needle mover analysis

Step 6: Configure behavioral event models​

HubSpot tracks behavioral events — website visits, form fills, email opens and clicks, meeting bookings — for known contacts. Each event type can be a separate non-product activity model on the account timeline.

Configure page views and form submissions:

"Configure HubSpot page view and form submission non-product activity models"

Configure all available event types:

"Configure non-product activity models for all six HubSpot behavioral event types"

The six available event types are: page views, form submissions, email opens, email link clicks, meeting bookings, and blog subscriptions.

Account resolution for events

Behavioral events resolve account_id by matching the visitor email to your users model. Events from visitors whose emails aren't in FunnelStory as users will be excluded. This is intentional — it keeps behavioral data scoped to accounts you actively manage.

Configuring everything at once​

If you want to set up all models in a single conversation:

"Configure all standard HubSpot models — accounts, users, email conversations, notes, page views, and form submissions"

Claude will configure them in the correct dependency order, previewing each query before saving.

Refreshing models after configuration​

New models start with draft: false and are activated immediately, but they need a data refresh to populate. Either:

  • Wait — FunnelStory refreshes models on a schedule (typically every 6 hours).
  • Trigger manually — In Configuration → Data models, find the model and click Refresh now.

After the first refresh, open an account that has HubSpot deals and check its timeline for email conversations, notes, and activity events.

Troubleshooting​

SymptomLikely causeFix
Conversations model shows 0 rowsUsers model not configured, so contacts weren't syncedConfigure the users model and wait for a sync, then refresh the conversations model
Page views show 0 rowsVisitor emails don't match any FunnelStory usersConfirm HubSpot visitor tracking is identifying visitors after login; check that your users model covers the right contacts
Notes show 0 rowsCompanies weren't seeded before the syncEnsure the accounts model has refreshed at least once (which seeds the companies list); then refresh the notes model
Wrong accounts linked to emailsContact has multiple associatedcompanyid valuesReview the contact in HubSpot and confirm the correct primary company association