Brainforge Knowledge

README

4 min read

HubSpot Integration

On-demand enrichment for Linear sales tickets with HubSpot context, plus access and automation patterns for Brainforge.

Overview

  1. Agents in Cursor: HubSpot MCP is the default for search, reads, and any CRM operation the MCP tools support.
  2. API / CLI: use tools/hubspot-api-service (or direct REST) when MCP cannot perform the operation, when volume or speed favors a script (e.g. WBR dry-run), or for scheduled automation.
  3. Humans: the HubSpot web app for extended review, settings, and work that is faster in the UI.
  4. HubSpot → Linear enrichment: fetch deal/contact/company context and add to Linear tickets on-demand.
  5. Association mapping: traverse deals → contacts → companies for full context where needed.

RevOps / CRM hygiene (operations): property audits and cleanup logs live under knowledge/operations/sales/ (not knowledge/sales/ lead research).

CRM motions (which docs / skills to use)

MotionWhat it coversExamples
SalesNet-new pipeline, prospect accounts, GTM cadenceshubspot-new-opportunity, GTM WBR/MBR skills, lead plays; MCP for lookup, API/CLI for scripted deal create
PartnerCo-sell vendors, Control Centers, rep contacts, partnership Slack opspartner-hubspot-ops, partner-ae-advisory, partnership-hubspot-eod-payload, daily-partnership-refresh
CROFunnel metrics, rollups, ITS / closed-won reconciliation, property hygienehubspot-sales-funnel-hygiene, hubspot-sales-review-rollup, hubspot-its-monthly-sync, knowledge/operations/sales/

Skills live under .cursor/skills/ (symlinked from .agents/skills/). Technical playbook: hubspot-api-setup.md.

Architecture

Humans → HubSpot web app (deep UI work)

Agents (Cursor)
    ├── HubSpot MCP — default: search, read, discovery
    └── tools/hubspot-api-service + REST — when MCP lacks capability or batch/speed wins

Quick Start

1. Use the HubSpot app by default

For most day-to-day work, open HubSpot directly and inspect or update the CRM there.

2. Set Up HubSpot MCP (default for agents in Cursor)

Repo wiring uses stdio + private app token (see mcp.json and HUBSPOT_MCP_SETUP_STEPS.md). Hosted mcp.hubspot.com OAuth is not the committed path for Cursor DCR reasons — the setup doc explains.

Typical MCP capabilities include search, reads, and property discovery; use the API layer when a tool you need is missing or when you are running high-volume scripts.

3. Set Up HubSpot API Service (writes, scripts, enrichment)

cd tools/hubspot-api-service
npm install

Configure your HubSpot access token in environment variables:

export HUBSPOT_ACCESS_TOKEN=your_token_here

4. Enrich a Linear Ticket

When working on a sales ticket in Cursor:

"Enrich this ticket with HubSpot context"

Or link to a specific deal:

"Link this ticket to HubSpot deal SAL-649"

Usage Examples

HubSpot app first

  • Review deal, company, and contact records directly in HubSpot
  • Confirm pipeline stage before making delivery or staffing assumptions
  • Prefer app-driven manual edits for normal human workflows

Natural language queries (HubSpot MCP — default)

  • “Show me all deals for Inteleos”
  • “What’s the status of deal X?”
  • “Who are the contacts on the Inteleos deal?”
  • “Get contact details for Juan Sanchez”

Writes and automation (API / service — when MCP cannot or should not)

Use tools/hubspot-api-service (or direct REST) when MCP does not expose the write, or for batch jobs:

  • “Create a deal for Inteleos with amount $50K” (scripted create — e.g. log-new-opportunity)
  • “Move Inteleos deal to ‘Qualified To Buy’ stage”
  • “Update deal close date to March 1, 2026”
  • “Add note to Inteleos deal: ‘SOW sent, awaiting NDA’” (note POST pattern in hubspot-api-setup.md)

Enrichment Operations

  • “Enrich this ticket with HubSpot context”
  • “Link this ticket to the Inteleos deal”
  • “Show me the full HubSpot context for this lead”

Components

  • mcp-config/: HubSpot MCP server configuration and setup guide
  • api-service/: Node.js service for HubSpot API operations
  • enrichment/: Linear ticket enrichment logic

Authentication

  • HubSpot app: normal browser login for humans
  • MCP (committed repo wiring): stdio + private app token → same token class as automation; see hubspot-api-setup.md
  • MCP (optional hosted / personal config): OAuth + PKCE against HubSpot’s hosted MCP — see HUBSPOT_MCP_SETUP_STEPS.md intro
  • API service: write-capable private app token for scripts, CLI, and jobs (tools/hubspot-api-service)

Credential Management: See CREDENTIALS.md for detailed credential setup, including 1Password CLI integration.

See setup.md for authentication setup.

Future Platform Integration

The API service can be deployed as a standalone service (e.g., on Railway) or integrated into existing platform infrastructure for application-level HubSpot operations.

Documentation

Graph View