Bojan Bojan
Ask AI
I am the Great and Powerful Oz, keeper of Bojan's secrets and his 298 five-star reviews. Step forward and ask, traveler, or tell me who you are and I shall tailor the spectacle.
I'm hiringI have a projectJust curiousAI & platforms
powered by cloudflare workers ai · llama
← All writing
SampleHQNov 15, 20259 min read

Building a Better HubSpot Integration with MCP, Test Accounts, and App Cards

When people think “HubSpot integration,” they usually picture a few API calls, some brittle webhooks, and a staging portal that never quite behaves like production. That used to be me, too. But with HubSpot’s new developer stack – local MCP server, configurable test accounts, and React-based app cards – you can build and test integrations

When people think “HubSpot integration,” they usually picture a few API calls, some brittle webhooks, and a staging portal that never quite behaves like production.

That used to be me, too.

But with HubSpot’s new developer stack – local MCP server, configurable test accounts, and React-based app cards – you can build and test integrations like a real product team instead of a collection of scripts taped together.

In this article, I’ll walk through how I’m using these tools to build a deep HubSpot integration for a WordPress-based SaaS (SampleHQ), and how you can steal the same workflow for your own app.

We’ll cover:

1. The Problem: CRM Integrations Are Usually Held Together with Duct Tape

A typical integration story looks like this:

If your app needs to:

…that kind of chaos stops being “annoying” and starts being dangerous.

The new HubSpot dev tools solve three big problems:

  1. Context – the MCP server gives your AI assistant real knowledge of HubSpot’s CLI, project structure, and docs.
  2. Isolation – configurable test accounts let you spin up portals that simulate different subscription tiers and hubs.
  3. Embedded UX – app cards let you place your app’s logic directly on contact records (or other objects), instead of forcing reps to live in two tabs.

Let’s wire those pieces together.

2. Set Up the HubSpot MCP Server in Your IDE

First step: give your AI assistant actual access to HubSpot’s developer context, instead of treating it like just another chatbot.

HubSpot ships a developer MCP server that runs locally and talks to your IDE / AI client. Once installed, it can:

Prerequisites

Install / update the CLI:

npm install -g @hubspot/cli@latest

Run MCP setup

In your terminal:

hs mcp setup

You’ll be prompted to select which client to connect (e.g., Cursor, Claude Code, VS Code). Once you pick your client and finish setup, restart the client so it can see the new MCP server.

Now your AI assistant can answer questions like:

Instead of copy-pasting from docs, you’re effectively pair programming with the HubSpot platform itself.

3. Use Configurable Test Accounts Instead of Torturing One Sandbox

Next, you need somewhere safe (and realistic) to test all this.

HubSpot’s configurable test accounts let you spin up developer portals that simulate specific subscription mixes and tiers – Starter, Professional, Enterprise, per hub. You can create them either via the CLI or in the UI.

Requirement: your project must be on platform version 2025.2+ and CLI 7.6.0+.

Option A: Create a test account from scratch (CLI)

hs test-account create

Then choose:

HubSpot creates the account and prints the Hub ID. You can then:

Option B: Create from a config file (recommended for teams & CI)

For repeatable setups, generate a JSON config:

hs test-account create-config

The prompts are similar (name, description, subscriptions), but this time HubSpot writes a JSON file like:

{
  "accountName": "AllHubsProfessional",
  "description": "Professional test account",
  "marketingLevel": "PROFESSIONAL",
  "opsLevel": "PROFESSIONAL",
  "serviceLevel": "PROFESSIONAL",
  "salesLevel": "PROFESSIONAL",
  "contentLevel": "PROFESSIONAL"
}

Now you can create accounts on demand:

hs test-account create --config-path ./test-portal-config.json

This is perfect when you want:

…and you want your CI/CD pipeline to spin up portals automatically during integration tests.

4. Import Realistic Test Data into Your Portal

An empty CRM isn’t very useful for testing.

HubSpot lets you seed test accounts with CRM data using the CLI and the CRM imports API behind the scenes.

The pattern:

  1. One or more CSV files with the actual data (contacts, companies, etc.)
  2. One JSON configuration file that tells HubSpot how to map columns to properties

Example JSON for importing contacts and companies:

{
  "name": "Test account data import (contact and company)",
  "importOperations": {
    "0-1": "CREATE",
    "0-2": "CREATE"
  },
  "files": [
    {
      "fileName": "contact-data.csv",
      "fileFormat": "CSV",
      "fileImportPage": {
        "hasHeader": true,
        "columnMappings": [
          {
            "columnObjectTypeId": "0-1",
            "columnName": "First Name",
            "propertyName": "firstname"
          },
          {
            "columnObjectTypeId": "0-1",
            "columnName": "Email",
            "propertyName": "email",
            "columnType": "HUBSPOT_ALTERNATE_ID"
          }
        ]
      }
    },
    {
      "fileName": "company-data.csv",
      "fileFormat": "CSV",
      "fileImportPage": {
        "hasHeader": true,
        "columnMappings": [
          {
            "columnObjectTypeId": "0-2",
            "columnName": "Company domain name",
            "propertyName": "domain",
            "columnType": "HUBSPOT_ALTERNATE_ID"
          }
        ]
      }
    }
  ]
}

Place the JSON and CSV files in the same directory, then run:

hs test-account import-data

The CLI will ask:

Then it fires the CRM imports API and gives you a link to the imports dashboard so you can monitor progress and errors.

For something like SampleHQ, this is where I’ll import:

That way, when the app card loads, it has real-looking data to work with.

5. Build a HubSpot App Card That Talks to Your App

Now the fun part: having your app actually show up inside HubSpot.

On the latest developer platform (2025.2), you can build React-based app cards that live on object records (like contacts). Perfect for showing:

Step 1 – Add a card to your HubSpot project

From your project directory:

hs project add

When prompted for a component, select Card.

HubSpot scaffolds:

myProject
└── src/
    └── app/
        └── cards/
            ├── NewCard-hsmeta.json
            ├── NewCard.jsx
            └── package.json

Step 2 – Install deps & upload the project

Install card dependencies:

hs project install-deps

Then upload:

hs project upload
# or, for a specific account:
hs project upload --account YOUR_TEST_HUB_ID

You can open the project in the browser with:

hs project open

From there, install the app into your test account via the Distribution tab → Install now.

Step 3 – Add the card to the contact record UI

In your HubSpot test account:

  1. Go to CRM → Contacts
  2. Open any contact
  3. At the top of the middle column, click Customize → Default view
  4. Click the + where you want your card
  5. In the right sidebar, open Card library → Card types → App
  6. Add your new app card, then Save and exit

Now your boilerplate card appears on contact records.

Step 4 – Start local development

To get instant reloads during development:

hs project dev

You’ll see a “Developing locally” tag on the card. Any changes to .jsx / .tsx files will live-reload into that card.

This is where your integration becomes tangible:

6. Where the WordPress Plugin Fits In

In my case, the backend is a multi-tenant WordPress plugin (samplehq-core) that:

The app card becomes the front door for HubSpot users:

On the WordPress side, everything is multi-tenant-safe and CRM-agnostic; HubSpot is just one of the registered CRM clients. But from the HubSpot user’s point of view, it feels like a native card.

7. Automate It with GitHub Actions and Test Accounts

The last step is to stop treating this as a “thing you click by hand” and start treating it like a proper pipeline.

Because test accounts are configurable and scriptable, you can:

Add GitHub Actions on top and you get a loop like:

  1. CI job creates a test account from a config file
  2. It imports a canned dataset (contacts, companies, demo deals)
  3. It deploys the latest build of your HubSpot project
  4. It runs E2E tests against your app card + backend APIs
  5. It tears down or reuses the test account as needed

For apps that also live in a separate backend (like a WordPress multisite), you can:

No more “it works in my portal” debugging.

8. Putting It All Together

If you’re building a serious HubSpot integration today, the stack I’d recommend looks like this:

Once you wire these pieces together, “HubSpot integration” stops being a spaghetti of webhooks and ad-hoc scripts, and starts feeling like a product surface you can ship features into.

Related writing
Jun 13, 2026

From Zapier to AI Agents: The Four Levels of Business Automation

Jun 03, 2026

Every WordPress Error Page Beyond 404 Is Broken. I Built a Plugin to Fix Them.

May 29, 2026

Your Git Log Is a Legal Document