HubSpot

• Per-user OAuth2 — central client (oauthCentral, recommended) — one HubSpot OAuth application is registered once by the platform maintainer; every end user signs in with their own HubSpot portal. Nothing to register per workspace: each one just installs the app and clicks Connect.
• Per-user OAuth2 — tenant client (oauth) — paste your own HubSpot OAuth client ID/secret in the connector config app. Each user signs in with their own account against your client (authorization-code + PKCE flow).
• Private App token (accessToken) — a caller-managed HubSpot Private App access token (PAT), used as-is with no exchange. Best for service-account / non-interactive automations where a single identity is preferable.

​

Who is this for?

​

Prerequisites

• A HubSpot account with access to the portal you want to expose.
• For the OAuth modes — a HubSpot OAuth application. HubSpot’s Developer Platform 2025.2 retired the legacy Public Apps UI: the OAuth app is now declared as code in a HubSpot project and deployed via the HubSpot CLI (from a free HubSpot developer account at developers.hubspot.com, separate from any CRM account). The platform maintainer registers one app for the central mode; a workspace can also register its own for the tenant mode. Copy the Client ID and Client Secret from the deployed app’s Auth tab.
• For the Private App token mode — a Private App access token created at HubSpot Settings → Integrations → Private Apps (https://app.hubspot.com/private-apps/<portal-id>), with the scopes covering the operations you intend to call.
• OAuth scopes — the connector requests the free-tier essentials by default (oauth, crm.objects.contacts.*, crm.objects.companies.*, crm.objects.deals.*, crm.objects.owners.read, tickets). Paid-tier features (lists, content, automation, forms, files) require their own scopes and a matching HubSpot subscription; every requested scope must be declared in the deployed app’s requiredScopes / optionalScopes.
• Base URL: https://api.hubapi.com (single host).

<api-url>/workspaces/slug:hubspot/webhooks/oauthCallback

context_id,agent_id,user_id

context_id,agent_id,user_id

You have access to the HubSpot MCP server. Use it whenever the user asks about CRM data — contacts, companies, deals, tickets, engagements, pipelines or marketing assets (forms, emails, workflows). Each tool is an entity that takes an `action` argument. Always prefer `action: search` over `action: list` for filtered lookups. For batch work, use the `batch*` actions instead of looping individual calls. Always confirm with the user before destructive actions (archive, delete, batchArchive, unenrollContact, removeMembers).

oauth crm.objects.contacts.read crm.objects.companies.read crm.objects.deals.read crm.objects.owners.read tickets

{
  "name": "contacts",
  "arguments": {
    "action": "search",
    "filterGroups": [
      {
        "filters": [
          { "propertyName": "email", "operator": "EQ", "value": "alice@acme.com" }
        ]
      }
    ],
    "properties": ["email", "firstname", "lastname", "lifecyclestage"],
    "limit": 1
  }
}

{
  "name": "deals",
  "arguments": {
    "action": "create",
    "properties": {
      "dealname": "Acme — annual contract",
      "amount": "120000",
      "dealstage": "appointmentscheduled",
      "pipeline": "default",
      "closedate": "2026-09-30"
    },
    "associations": [
      {
        "to": { "id": "11223344" },
        "types": [
          { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 5 }
        ]
      }
    ]
  }
}

{
  "name": "lists",
  "arguments": {
    "action": "addMembers",
    "listId": "12345"
  }
}

{
  "name": "marketingEmails",
  "arguments": {
    "action": "sendTransactional",
    "emailId": "67890",
    "message": {
      "to": "alice@acme.com",
      "from": "noreply@acme.com"
    },
    "contactProperties": { "firstname": "Alice" },
    "customProperties": { "orderId": "ORD-12345" }
  }
}

{
  "name": "workflows",
  "arguments": {
    "action": "enrollContact",
    "workflowId": "98765",
    "email": "alice@acme.com"
  }
}

- Hubspot.searchContacts:
    filterGroups:
      - filters:
          - propertyName: email
            operator: EQ
            value: '{{lead.email}}'
    properties:
      - email
      - firstname
      - lastname
      - lifecyclestage
    limit: 1
    output: matched

- Hubspot.createDeal:
    properties:
      dealname: '{{opportunity.name}}'
      amount: '{{opportunity.amount}}'
      dealstage: 'appointmentscheduled'
      pipeline: 'default'
      closedate: '{{opportunity.closeDate}}'
    associations:
      - to:
          id: '{{companyId}}'
        types:
          - associationCategory: HUBSPOT_DEFINED
            associationTypeId: 5
    output: created

- Hubspot.addListMembers:
    listId: '{{leadsListId}}'
    recordIds:
      - '{{contactId}}'

- Hubspot.sendTransactionalEmail:
    emailId: '{{templateId}}'
    message:
      to: '{{lead.email}}'
      from: 'noreply@acme.com'
    contactProperties:
      firstname: '{{lead.firstName}}'
    customProperties:
      orderId: '{{order.id}}'
      orderTotal: '{{order.total}}'

- Hubspot.batchCreateContacts:
    inputs:
      - properties:
          email: 'alice@acme.com'
          firstname: 'Alice'
          lastname: 'Doe'
      - properties:
          email: 'bob@acme.com'
          firstname: 'Bob'
          lastname: 'Smith'
    output: batchResult

​

Error Handling

​

Common Issues

​

External Resources