HubSpot Connector

The HubSpot connector enables AxonFlow agents to interact with HubSpot CRM for managing contacts, companies, deals, and tickets with full policy enforcement and audit logging.

Overview

Property	Value
Type	hubspot
Edition	Enterprise
Auth Methods	OAuth 2.0, Private App Access Token
Capabilities	query, execute, search, associations, batch_operations

Use Cases

• Query contacts and companies for customer support agents
• Create and update deals in sales automation workflows
• Search CRM records for lead qualification bots
• Manage tickets for helpdesk automation

Prerequisites

• AxonFlow Enterprise license (requires Enterprise Edition)
• HubSpot account with API access enabled
• One of the following authentication methods:
  • Private App Access Token (recommended for server-to-server)
  • OAuth 2.0 credentials (for user-context operations)
• Required HubSpot scopes: crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.companies.read, crm.objects.deals.read, crm.objects.deals.write, crm.objects.custom.read

HubSpot Private App Setup

1. In HubSpot, go to Settings > Integrations > Private Apps
2. Click Create a private app
3. Name the app (e.g., "AxonFlow Integration")
4. Under Scopes, select the required CRM scopes listed above
5. Click Create app and copy the access token

Configuration

Environment Variables

# Required
MCP_hubspot_ACCESS_TOKEN="pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Optional
MCP_hubspot_PORTAL_ID="12345678"
MCP_hubspot_TIMEOUT="30s"
MCP_hubspot_MAX_RETRIES="3"
MCP_hubspot_RATE_LIMIT="100"  # Requests per 10 seconds

Configuration Options

Option	Type	Required	Default	Description
access_token	string	Yes	-	HubSpot Private App access token or OAuth token
portal_id	string	No	-	HubSpot portal (account) ID
timeout	string	No	30s	Request timeout
max_retries	integer	No	3	Maximum retry attempts on transient failures
rate_limit	integer	No	100	Max requests per 10-second window

Connector Config (Customer Portal)

{
  "name": "hubspot-crm",
  "type": "hubspot",
  "options": {
    "portal_id": "12345678",
    "timeout": 30,
    "max_retries": 3,
    "rate_limit": 100
  },
  "credentials": {
    "access_token": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Installation

Install the HubSpot connector via the connector marketplace API:

curl -X POST http://localhost:8081/api/v1/connectors/hubspot/install \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "hubspot-crm",
    "config": {
      "access_token": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "portal_id": "12345678"
    }
  }'

Operations

Search Contacts

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "connector": "hubspot-crm",
    "statement": "contacts.search",
    "parameters": {
      "filters": [
        {
          "propertyName": "email",
          "operator": "CONTAINS_TOKEN",
          "value": "example.com"
        }
      ],
      "properties": ["email", "firstname", "lastname", "company", "phone"],
      "limit": 20
    }
  }'

Response:

{
  "success": true,
  "rows": [
    {
      "id": "501",
      "properties": {
        "email": "[email protected]",
        "firstname": "Alice",
        "lastname": "Johnson",
        "company": "Acme Corp",
        "phone": "+1-555-0100"
      },
      "createdAt": "2025-06-15T10:30:00Z",
      "updatedAt": "2025-12-01T14:20:00Z"
    }
  ],
  "row_count": 1,
  "duration_ms": 120,
  "connector": "hubspot-crm"
}

Create a Contact

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "hubspot-crm",
    "action": "contacts.create",
    "parameters": {
      "properties": {
        "email": "[email protected]",
        "firstname": "Bob",
        "lastname": "Smith",
        "company": "Widget Co",
        "lifecyclestage": "lead"
      }
    }
  }'

Response:

{
  "success": true,
  "rows_affected": 1,
  "message": "Contact created (id=502)",
  "duration_ms": 95,
  "connector": "hubspot-crm"
}

Search Deals

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -d '{
    "connector": "hubspot-crm",
    "statement": "deals.search",
    "parameters": {
      "filters": [
        {
          "propertyName": "dealstage",
          "operator": "EQ",
          "value": "closedwon"
        },
        {
          "propertyName": "amount",
          "operator": "GTE",
          "value": "50000"
        }
      ],
      "properties": ["dealname", "amount", "dealstage", "closedate", "pipeline"],
      "sorts": [{"propertyName": "amount", "direction": "DESCENDING"}],
      "limit": 10
    }
  }'

Update a Deal

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "hubspot-crm",
    "action": "deals.update",
    "parameters": {
      "id": "deal-7890",
      "properties": {
        "dealstage": "closedwon",
        "amount": "75000",
        "closedate": "2025-12-15"
      }
    }
  }'

Search Companies

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -d '{
    "connector": "hubspot-crm",
    "statement": "companies.search",
    "parameters": {
      "filters": [
        {
          "propertyName": "industry",
          "operator": "EQ",
          "value": "TECHNOLOGY"
        }
      ],
      "properties": ["name", "domain", "industry", "numberofemployees"],
      "limit": 25
    }
  }'

Supported Operations

Operation	Description
contacts.search	Search contacts by properties and filters
contacts.create	Create a new contact
contacts.update	Update contact properties
companies.search	Search companies by properties
companies.create	Create a new company
deals.search	Query deals with filters and sorting
deals.create	Create a new deal
deals.update	Update deal properties
tickets.search	Search support tickets
tickets.create	Create a new ticket

Limitations

• Rate limits: HubSpot enforces API rate limits (100 requests per 10 seconds for Private Apps, varies by plan). The connector handles 429 responses with automatic backoff.
• Search limits: Search endpoints return a maximum of 10,000 results. Use filters to narrow results.
• Batch size: Batch operations are limited to 100 records per request.
• Property limits: A maximum of 20 properties can be requested per search query.
• Association depth: Only direct associations are returned; nested associations require separate queries.

Troubleshooting

Authentication Failed (401)

• Verify the Private App access token is correct and not expired
• Check that the Private App has the required scopes enabled
• Ensure the HubSpot account subscription supports API access

Rate Limited (429)

• The connector automatically retries with exponential backoff on 429 responses
• Reduce rate_limit configuration to stay within HubSpot's limits
• Consider using batch endpoints for bulk operations

Missing Properties in Response

• Verify the property names are correct (use HubSpot's property API to list available properties)
• Check that the Private App scope includes read access for the object type
• Custom properties must be referenced by their internal name, not display label

Health Check

curl https://your-axonflow.example.com/mcp/connectors/hubspot-crm/health

Response:

{
  "healthy": true,
  "latency_ms": 85,
  "details": {
    "portal_id": "12345678",
    "auth_type": "private_app",
    "rate_limit_remaining": "92"
  }
}

Related

• Salesforce Connector
• Jira Connector
• MCP Overview
• Connector SDK