HubSpot API + MCP (2026): Enterprise CRM with Official Remote MCP

HubSpot’s API v3 is one of the most mature CRM + marketing APIs in the industry. Wide surface across contacts, companies, deals, tickets, marketing emails, workflows, and lists. OAuth 2.0 + private app tokens, well-documented per-portal rate limits (100 requests per 10 seconds standard tier, higher for Enterprise), 7 official SDKs. In 2026 HubSpot added a major differentiator: an official remote MCP server for AI agents, letting Claude Desktop, Cursor, VSCode, and ChatGPT operate the HubSpot CRM through natural language. This tab inventories the API surface, MCP capabilities, and the gotchas developers need to evaluate before committing.

At a glance

MCP integration in 2026

Model Context Protocol is the standard for connecting LLM agents to external tools. HubSpot’s MCP server was released with unusually wide CRM coverage from launch, positioning HubSpot as one of the AI-agent-first CRM platforms in 2026.

Available MCP servers for HubSpot

Three ways to reach HubSpot from an AI agent as of August 2026. The first is HubSpot’s official remote server — the most feature-complete option.

API v3 essentials

HubSpot API v3 is REST-based with JSON payloads. Endpoint paths follow object-oriented conventions (/crm/v3/objects/{objectType}). Both v3 and legacy v1 endpoints remain supported for backward compatibility.

The 100-requests-per-10-seconds rule is the number one thing developers underestimate. At standard tier, you can burst 100 requests in 1 second but not another 100 for the next 9 seconds. Design your request patterns around this rolling window — batch endpoints are essential for any bulk operation.

Authentication methods

Private app tokens (recommended for internal use)

Generate a private app in your HubSpot portal at Settings › Integrations › Private Apps. Assign granular scopes at creation. Use the resulting access token in the Authorization header:

Authorization: Bearer pat-XXXXXXXXXXXXXXXX
Content-Type: application/json

Private app tokens are the recommended pattern for internal integrations (custom apps, data pipelines, admin scripts). Scoped per app, revocable per app, no OAuth flow complexity.

OAuth 2.0 (required for public apps)

Required for apps published on the HubSpot App Marketplace or for any integration that acts on behalf of multiple HubSpot users. Standard three-leg authorization code flow. Register your app in the HubSpot Developer Portal to receive Client ID + Client Secret. Access tokens expire after 30 minutes; refresh tokens are long-lived.

Rate limits

HubSpot publishes rate limits per portal (customer account), with tier-based scaling. Understanding the 100/10s rule is essential for any non-trivial integration.

The 100/10s per portal is portal-wide — shared across all API keys, private apps, and integrations accessing your HubSpot portal. If you run Zapier + a custom sync app + an OAuth integration simultaneously, they compete for the same 100/10s budget. Coordinate integration timing to avoid mutual throttling.

Official SDKs

Seven official client libraries maintained by HubSpot, plus TypeScript type definitions.

Endpoints reference

The endpoint groups you will actually use in production. Full reference at developers.hubspot.com/docs/api/overview.

Code examples

Node.js: create or update a contact

const hubspot = require('@hubspot/api-client');

const client = new hubspot.Client({
  accessToken: 'pat-YOUR_PRIVATE_APP_TOKEN'
});

async function upsertContact(email) {
  try {
    // Try to find existing contact by email
    const found = await client.crm.contacts.searchApi.doSearch({
      filterGroups: [{
        filters: [{ propertyName: 'email', operator: 'EQ', value: email }]
      }]
    });

    if (found.results.length > 0) {
      const id = found.results[0].id;
      await client.crm.contacts.basicApi.update(id, {
        properties: { firstname: 'Alaa', lastname: 'Touil' }
      });
      console.log(`Updated contact ${id}`);
    } else {
      const created = await client.crm.contacts.basicApi.create({
        properties: { email, firstname: 'Alaa', lastname: 'Touil' }
      });
      console.log(`Created contact ${created.id}`);
    }
  } catch (err) {
    console.error(err.message);
  }
}

upsertContact('user@example.com');

Python: send a transactional email (requires add-on)

from hubspot import HubSpot
from hubspot.marketing.transactional import PublicSingleSendRequestEgg

client = HubSpot(access_token='pat-YOUR_PRIVATE_APP_TOKEN')

request = PublicSingleSendRequestEgg(
    email_id=123456,  # Transactional email template ID
    message={
        'to': 'customer@example.com',
        'from': 'sender@yourbrand.com',
        'reply_to': ['support@yourbrand.com']
    },
    contact_properties={'firstname': 'Alaa'},
    custom_properties={'order_id': 'ORD-1234'}
)

response = client.marketing.transactional.single_send_api.send_email(
    public_single_send_request_egg=request
)

print(f"Sent: {response.status_id}")

Common gotchas

Deprecations and changelog

HubSpot maintains developer changelogs at developers.hubspot.com/changelog. Key items:

• API v3 is current. Modern REST API with granular scopes and batch endpoints.
• Legacy API keys deprecated (Nov 2022). Old-style single-key authentication was replaced by private app tokens for internal use and OAuth for public apps. Migrate immediately if you still use API keys.
• Official HubSpot Remote MCP Server released in 2026. Wide CRM coverage from launch. Positioned as core AI-agent platform.
• Custom objects API expanded through 2024-2025 for Enterprise customers modeling non-standard entities.
• Breeze AI introduced 2024, matured through 2026 with content generation, meeting notes, forecasting, and prospect research capabilities.

Frequently asked questions