HubSpot - Prisme.ai

The HubSpot connector provides read/write access to a HubSpot portal through the HubSpot REST API. It can be used either as a Builder app (automations call HubSpot instructions directly) or as a remote MCP server consumed by an AI agent. Two authentication modes coexist on the same MCP endpoint:

Central OAuth2 (recommended) — one HubSpot Public App is registered once by the Prisme.ai workspace admin; every end user signs in with their own HubSpot portal. Nothing to install per tenant. Requires the platform admin to grant the HubSpot capability in Prisme.ai Governance (see below).
Tenant PAT — install the HubSpot app in your workspace and paste a Private App access token. Shared across the workspace’s users; no per-user sign-in.

The connector exposes ~120 operations grouped into 18 entity tools covering the CRM (contacts, companies, deals, tickets, engagements, associations, pipelines, properties, owners, lists) and the Marketing layer (forms, marketing emails, workflows, files).

CRM Records

Contacts, companies, deals and tickets with list/search/get/create/update/archive plus batch and merge operations

Engagements & Pipelines

Notes, tasks, calls, emails and meetings; pipelines and stages; properties and property groups; owners and lists

Central OAuth or PAT

One shared HubSpot Public App with per-user sign-in, or a tenant-level Private App Token — both modes coexist on the same MCP endpoint

Prerequisites

A HubSpot account with access to the portal you want to expose.
For the central OAuth mode — the platform admin has registered ONE HubSpot Public App through the HubSpot Developer Platform 2025.2 (CLI Projects), declared the OAuth scopes the connector needs, allowlisted the portals that can install it (Private distribution caps at 10 portals; Solution Partners get 100), and stored its Client ID + Client Secret in the Secrets of the central hubspot workspace. The end user only needs to click Connect once and select their portal on the HubSpot consent screen.
For the tenant PAT 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 resources you intend to read/write (crm.objects.contacts.*, crm.objects.companies.*, tickets, content, automation, forms, files, etc.), pasted into the installed app instance.
Base URL (default: https://api.hubapi.com).

The two modes are mutually exclusive per MCP call: callers identify themselves either by being authenticated to Prisme.ai (central) or by sending the mcp-api-key header (tenant). The same workspace can serve both at the same time.

HubSpot has no standard RFC 7009 revocation endpoint. The disconnect tool deletes the platform-stored tokens but cannot revoke them at HubSpot — refresh tokens may still be valid until they naturally expire (typically 6 months idle).

Usage as App
Usage as MCP
Setup OAuth

Installation

Go to Apps in your workspace
Search for HubSpot and install it
Open the app instance configuration and fill in either the PAT or the OAuth client credentials

Configuration

Field	Description
HubSpot API Base URL	Base URL of the HubSpot API (default `https://api.hubapi.com`)
HubSpot Private App Token (PAT)	Private App access token for this tenant — shared across the tenant’s users. Required for tenant-mode access (header `mcp-api-key`). Leave empty to use the central OAuth shared by the platform admin.
MCP Endpoint	Auto-populated on install — URL of the MCP endpoint for this instance. Pass header `mcp-api-key` to use tenant PAT mode; omit the header to use shared OAuth (user-delegated, central).
MCP API Key	Auto-populated on install — signed key used in the `mcp-api-key` header (tenant PAT mode). Do not modify.

OAuth credentials (Client ID / Client Secret / authorization URL / token URL / scopes) are NOT part of the app instance config anymore — they live in the Secrets of the central hubspot workspace and are shared by all callers in central mode. See the Setup (one-time, platform admin) section above.

Available Instructions

Every instruction resolves credentials from the workspace configuration. CRM list operations accept limit (default 100) and after for cursor pagination, plus properties to request specific fields. Most CRM tools accept an optional objectType to override the default object type — useful for custom objects.

Contacts

Instruction	Arguments
`listContacts`	`limit`, `after`, `properties`, `propertiesWithHistory`, `associations`, `archived`
`getContact`	`contactId`*, `properties`, `propertiesWithHistory`, `associations`, `archived`, `idProperty`
`createContact`	`properties`*, `associations`
`updateContact`	`contactId`, `properties`, `idProperty`
`archiveContact`	`contactId`*
`searchContacts`	`filterGroups`, `sorts`, `query`, `properties`, `limit`, `after`
`mergeContacts`	`primaryObjectId`, `objectIdToMerge`
`batchReadContacts`	`inputs`*, `properties`, `propertiesWithHistory`, `idProperty`
`batchCreateContacts`	`inputs`*
`batchUpdateContacts`	`inputs`*
`batchArchiveContacts`	`inputs`*

Companies

Same shape as contacts: listCompanies, getCompany, createCompany, updateCompany, archiveCompany, searchCompanies, mergeCompanies, batchReadCompanies, batchCreateCompanies, batchUpdateCompanies, batchArchiveCompanies.

Deals

Same shape as contacts: listDeals, getDeal, createDeal, updateDeal, archiveDeal, searchDeals, mergeDeals, batchReadDeals, batchCreateDeals, batchUpdateDeals, batchArchiveDeals.

Tickets

listTickets, getTicket, createTicket, updateTicket, archiveTicket, searchTickets, batchReadTickets, batchCreateTickets, batchUpdateTickets, batchArchiveTickets (no merge).

Associations

Instruction	Arguments
`listAssociations`	`fromObjectType`, `fromObjectId`, `toObjectType`*, `after`, `limit`
`createAssociation`	`fromObjectType`, `fromObjectId`, `toObjectType`, `toObjectId`, `associationCategory`, `associationTypeId`
`archiveAssociation`	`fromObjectType`, `fromObjectId`, `toObjectType`, `toObjectId`

Engagements

Notes, tasks, calls, emails and meetings share the same shape: list, get, create, update, archive.

Instruction	Arguments
`listNotes` / `listTasks` / `listCalls` / `listEmails` / `listMeetings`	`limit`, `after`, `properties`, `associations`, `archived`
`getNote` / `getTask` / `getCall` / `getEmail` / `getMeeting`	`engagementId`*, `properties`, `associations`, `archived`
`createNote` / `createTask` / `createCall` / `createEmail` / `createMeeting`	`properties`*, `associations`
`updateNote` / `updateTask` / `updateCall` / `updateEmail` / `updateMeeting`	`engagementId`, `properties`
`archiveNote` / `archiveTask` / `archiveCall` / `archiveEmail` / `archiveMeeting`	`engagementId`*

Pipelines

Instruction	Arguments
`listPipelines`	`objectType`*
`getPipeline`	`objectType`, `pipelineId`
`createPipeline`	`objectType`, `label`, `stages`*, `displayOrder`
`updatePipeline`	`objectType`, `pipelineId`, `label`, `stages`, `displayOrder`
`archivePipeline`	`objectType`, `pipelineId`
`listPipelineStages`	`objectType`, `pipelineId`
`getPipelineStage`	`objectType`, `pipelineId`, `stageId`*
`createPipelineStage`	`objectType`, `pipelineId`, `label`*, `metadata`, `displayOrder`
`updatePipelineStage`	`objectType`, `pipelineId`, `stageId`*, `label`, `metadata`, `displayOrder`
`archivePipelineStage`	`objectType`, `pipelineId`, `stageId`*

Properties

listProperties, getProperty, createProperty, updateProperty, archiveProperty, listPropertyGroups, createPropertyGroup, updatePropertyGroup, archivePropertyGroup.

Owners

Instruction	Arguments
`listOwners`	`email`, `after`, `limit`, `archived`
`getOwner`	`ownerId`*, `idProperty`

Lists

Instruction	Arguments
`createList`	`name`, `objectTypeId`, `processingType`*, `filterBranch`
`getList`	`listId`*, `includeFilters`
`updateList`	`listId`*, `name`
`deleteList`	`listId`*
`searchLists`	`query`, `count`, `offset`, `processingTypes`, `additionalProperties`
`addMembers`	`listId`, `recordIds`
`removeMembers`	`listId`, `recordIds`
`getMemberships`	`listId`*, `after`, `limit`

Forms

Instruction	Arguments
`listForms`	`after`, `limit`, `archived`, `formTypes`
`getForm`	`formId`*, `archived`
`createForm`	`name`, `formType`, `fieldGroups`, `configuration`
`updateForm`	`formId`*, `name`, `fieldGroups`, `configuration`
`archiveForm`	`formId`*
`submitForm`	`portalId`, `formGuid`, `fields`*, `context`, `legalConsentOptions`

Marketing Emails

Instruction	Arguments
`listMarketingEmails`	`after`, `limit`, `archived`, `sort`, `name`
`getMarketingEmail`	`emailId`*
`createMarketingEmail`	`name`*, `subject`, `subscription`, `content`
`updateMarketingEmail`	`emailId`*, `name`, `subject`, `subscription`, `content`
`archiveMarketingEmail`	`emailId`*
`sendTransactional`	`emailId`, `message`, `contactProperties`, `customProperties`

Workflows

Instruction	Arguments
`listWorkflows`	`limit`, `offset`
`getWorkflow`	`workflowId`*
`enrollContactInWorkflow`	`workflowId`, `email`
`unenrollContactFromWorkflow`	`workflowId`, `email`

Files

Instruction	Arguments
`listFiles`	`after`, `limit`, `parentFolderId`, `parentFolderPath`, `name`, `extension`
`getFile`	`fileId`*
`getSignedUrl`	`fileId`*, `expirationSeconds`, `upscale`
`archiveFile`	`fileId`*
`importFromUrl`	`name`, `url`, `folderId`, `folderPath`, `access`, `duplicateValidationStrategy`
`listFolders`	`after`, `limit`, `parentFolderId`, `name`
`createFolder`	`name`*, `parentFolderId`, `parentPath`
`archiveFolder`	`folderId`*

Arguments flagged with * are required.

DSUL Examples

Look up a contact by email

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

Create a deal and associate it to a company

- Hubspot.deals:
    action: create
    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

Add a contact to a static list

- Hubspot.lists:
    action: addMembers
    listId: '{{leadsListId}}'
    recordIds:
      - '{{contactId}}'

Send a transactional email

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

Bulk-import contacts

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

The HubSpot connector ships with a built-in MCP server hosted at one stable URL per environment:

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

The same endpoint serves two authentication modes depending on whether the caller sends an mcp-api-key header.

Plug into an Agent Creator capability (central OAuth)

The preferred path for human-facing agents. End users sign in with their own HubSpot portal; tokens are stored against their Prisme.ai user identity, never shared with other users of the same workspace.

Prerequisites

The platform admin has completed the Setup (one-time, platform admin) section above: HubSpot Public App deployed via the CLI, the calling user’s portal allowlisted, hubspotOauthClientId + hubspotOauthClientSecret stored in the central workspace secrets, and the HubSpot capability granted in Governance to the right roles.

Open Agent Creator

Switch to Agent Creator and open the agent you want to extend.

Add the HubSpot capability

Add the HubSpot capability to the agent. No URL, no mcp-api-key to paste — the central endpoint is pre-wired and the caller is identified by the Prisme.ai session of whoever is talking to the agent.

Brief the agent in its system prompt

Wiring the capability is not enough — the agent also needs to know the MCP exists and when to reach for it. Copy-pasteable starter:

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). Always prefer `*.search` over `*.list` for filtered lookups. For batch work, use `batchRead/Create/Update/Archive` instead of looping individual calls. If the user is not yet connected, call the `connect` tool to obtain a sign-in link; if they are already connected, call the relevant data tool directly. Always confirm with the user before destructive actions (archive, delete, batchArchive, unenrollContact, removeMembers).

Refine the trigger keywords (resource names, business domains, typical user phrasings) so the agent reliably picks up the right intent in your context.

First call → sign-in

On the first HubSpot tool call, the agent receives a connect_url. Open it in a new window: HubSpot lets the user pick the portal to authorize (from the allowlisted set) and review the requested scopes, then redirects back to a callback page that closes itself after 5 seconds. The agent retries the same tool call automatically.

Use this when one shared token is preferable to per-user OAuth — typical for service-account workflows, automations triggered by a non-interactive bot user, or environments where the central OAuth admin setup is not available.

Install the HubSpot app in your workspace

Open the workspace Imports panel, search for HubSpot and install it.

Paste a Private App access token

Open the freshly installed app instance settings, set the HubSpot API Base URL (if not https://api.hubapi.com) and the HubSpot Private App Token (PAT) (with the scopes covering the operations you intend to call). Save.

Copy the MCP endpoint and API key

Still on the app instance configuration page, copy the values of MCP Endpoint and MCP API Key — both are generated automatically on install. The endpoint is the same as the central one above; the mcp-api-key identifies your tenant.

Wire into Agent Creator

Add a new capability to the agent:

If a dedicated HubSpot tenant capability exists — select it and paste the MCP API Key into the mcp-api-key field.
Otherwise — select the generic custom_mcp capability, paste the MCP Endpoint into the Server URL field, then add an mcp-api-key entry to the Headers field:
```
{
  "mcp-api-key": "your-mcp-api-key"
}
```

Save

The agent now calls HubSpot through the tenant PAT — every user of this agent shares the same HubSpot identity (the owner of the PAT).

Legacy MCP install (Advanced → Tools)

Use this flow to plug the HubSpot MCP into an AI Knowledge agent that does not yet support the native MCP picker. Always paired with tenant PAT mode — the Advanced → Tools picker only sends the header path, not the central OAuth session.

Install the HubSpot app

Install and configure the app in the same workspace as your agent (see the Tenant PAT path above). Once configured, mcpEndpoint and mcpApiKey are auto-populated.

Copy the MCP credentials

Open the app instance config and copy the values of MCP Endpoint and MCP API Key.

Open your AI Knowledge project

Navigate to Advanced > Tools.

Add an MCP tool

Click Add and select the MCP tab.

Fill in the endpoint

Paste the MCP Endpoint URL copied from the app instance.

Add the auth header

In the Headers field, add the signed API key:

{
  "mcp-api-key": "your-mcp-api-key"
}

Save

The agent can now list and call HubSpot tools through the MCP endpoint.

The signed mcp-api-key encodes the workspace ID and a getConfig webhook URL. The MCP server validates the signature and resolves the tenant PAT server-side. The connect / disconnect tools are filtered out of tools/list in tenant mode — they only make sense for central OAuth.

Output Formats

Every tool accepts an outputFormat parameter that controls the MCP response shape:

verbose (default) — human-readable text for LLM consumption
structured — machine-readable JSON in structuredContent
both — both text and structured content

Available Tools

The MCP server exposes 18 entity-level tools (each with an action argument to select the operation) plus the 2 generic OAuth tools.

`contacts` / `companies` / `deals`

These three CRM tools share the same set of actions.

Action	Description
`list`	List records with pagination and property selection
`get`	Retrieve a single record by id (or by `idProperty`)
`create`	Create a record with properties and optional associations
`update`	Update a record by id
`archive`	Archive (soft-delete) a record
`search`	Full-text and structured search with filter groups, sorts and a `query` shortcut
`merge`	Merge two records into one (`primaryObjectId` ← `objectIdToMerge`)
`batchRead`	Read up to 100 records at once
`batchCreate`	Create up to 100 records in one call
`batchUpdate`	Update up to 100 records in one call
`batchArchive`	Archive up to 100 records in one call

`tickets`

Same actions as the CRM trio above, minus merge.

`associations`

Action	Description
`list`	List associations from a record to a target object type
`create`	Create an association between two records
`archive`	Remove an association between two records

`notes` / `tasks` / `calls` / `engagementEmails` / `meetings`

All five engagement tools share the same actions.

Action	Description
`list`	List engagements
`get`	Retrieve a single engagement
`create`	Create an engagement, optionally with associations to CRM records
`update`	Update an engagement
`archive`	Archive an engagement

`pipelines`

Action	Description
`list`	List pipelines for an object type
`get`	Retrieve a pipeline
`create`	Create a pipeline
`update`	Update a pipeline
`archive`	Archive a pipeline
`listStages`	List the stages of a pipeline
`getStage`	Retrieve a stage
`createStage`	Add a stage to a pipeline
`updateStage`	Update a stage
`archiveStage`	Archive a stage

`properties`

Action	Description
`list`	List properties for an object type
`get`	Retrieve a property
`create`	Create a property
`update`	Update a property
`archive`	Archive a property
`listGroups`	List property groups for an object type
`createGroup`	Create a property group
`updateGroup`	Update a property group
`archiveGroup`	Archive a property group

`owners`

Action	Description
`list`	List owners (optionally filter by email)
`get`	Retrieve an owner by id

`lists`

Action	Description
`create`	Create a list
`get`	Retrieve a list (optionally with filters)
`update`	Rename a list
`delete`	Delete a list
`search`	Search lists by name and processing type
`addMembers`	Add records to a static list
`removeMembers`	Remove records from a static list
`getMemberships`	List the members of a list

`forms`

Action	Description
`list`	List marketing forms
`get`	Retrieve a form
`create`	Create a form
`update`	Update a form
`archive`	Archive a form
`submit`	Submit values to a form on behalf of a visitor

`marketingEmails`

Action	Description
`list`	List marketing emails
`get`	Retrieve a marketing email
`create`	Create a marketing email
`update`	Update a marketing email
`archive`	Archive a marketing email
`sendTransactional`	Send a transactional single-send email to a recipient

`workflows`

Action	Description
`list`	List workflows
`get`	Retrieve a workflow
`enrollContact`	Enroll a contact in a workflow by email
`unenrollContact`	Unenroll a contact from a workflow by email

`files`

Action	Description
`list`	List files
`get`	Retrieve file metadata
`getSignedUrl`	Create a signed URL to download a file
`archive`	Archive a file
`importFromUrl`	Import a file from a public URL
`listFolders`	List folders
`createFolder`	Create a folder
`archiveFolder`	Archive a folder

OAuth Session

Tool	Description
`connect`	Initiate an OAuth connection to HubSpot. Returns a `connect_url` for the user to click. Prefer calling data tools directly — they auto-handle authentication.
`disconnect`	Disconnect the current HubSpot OAuth session and delete the stored tokens (HubSpot has no RFC 7009 revocation endpoint)

Tool Details

`contacts` (action: `search`)

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

Parameter	Required	Description
`action`	✓	Must be `search`
`filterGroups`	–	Array of `{ filters: [{ propertyName, operator, value }] }`. Filters inside a group are AND’d; groups are OR’d
`sorts`	–	Array of `{ propertyName, direction }`
`query`	–	Free-text query alternative to `filterGroups`
`properties`	–	Properties to include in the response
`limit`	–	Page size (max 100)
`after`	–	Cursor from a previous response (`paging.next.after`)

`deals` (action: `create`)

{
  "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 }
        ]
      }
    ]
  }
}

Parameter	Required	Description
`action`	✓	Must be `create`
`properties`	✓	Map of HubSpot deal properties
`associations`	–	Optional list of association targets (`{ to.id, types: [{ associationCategory, associationTypeId }] }`)

`lists` (action: `addMembers`)

{
  "name": "lists",
  "arguments": {
    "action": "addMembers",
    "listId": "12345",
    "recordIds": ["1001", "1002", "1003"]
  }
}

Parameter	Required	Description
`action`	✓	Must be `addMembers`
`listId`	✓	Target list ID
`recordIds`	✓	IDs of the records to add (only valid for static / `MANUAL` lists)

`marketingEmails` (action: `sendTransactional`)

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

Parameter	Required	Description
`action`	✓	Must be `sendTransactional`
`emailId`	✓	The single-send email template ID
`message`	✓	`{ to, from, cc, bcc, replyTo }`
`contactProperties`	–	Properties to set on the contact for personalization
`customProperties`	–	Custom merge tags resolved inside the email body

`workflows` (action: `enrollContact`)

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

Parameter	Required	Description
`action`	✓	Must be `enrollContact`
`workflowId`	✓	Target workflow
`email`	✓	Email of the contact to enroll

The central OAuth flow is set up once per environment by the Prisme.ai workspace admin. End users never touch any of this. HubSpot’s Developer Platform 2025.2 has retired the legacy Public Apps UI: the OAuth Public App config is now declared as code in a HubSpot project and deployed via the HubSpot CLI.

Prerequisites

Create a free HubSpot developer account at developers.hubspot.com (separate from any HubSpot CRM account), then install the CLI:

npm install -g @hubspot/cli@latest

The hubspot workspace ships with two ready-to-deploy projects under workspaces/hubspot/project/ — one per environment (sandbox/ and prod/). Each contains an app-hsmeta.json declaring the OAuth app’s redirect URI, required scopes, optional scopes, and permittedUrls.

Authenticate the CLI to your developer account

Run hs init from any of the project folders. It opens a browser to your developer account and writes a per-machine hubspot.config.yml (which is gitignored — it holds your personal access key).

cd workspaces/hubspot/project/sandbox  # or prod
hs init

This step authenticates the CLI for you, the developer. The end users’ OAuth flow is independent of this key — it relies only on the Client ID / Client Secret HubSpot will generate after deploy.

Deploy the project

hs project upload
hs project deploy

Repeat from workspaces/hubspot/project/prod when you’re ready to ship to production. Each deploy creates one HubSpot Public App in your developer dashboard with distribution: private — useful and self-contained, capped at 10 allowlisted portals (or 100 if you’re an HubSpot Solution Partner).

Allowlist the portals that may install the app

Open the deployed app in the HubSpot developer dashboard (https://app-eu1.hubspot.com/developer-projects/<accountId> or app.hubspot.com on the US region) → Auth → Allowlisted accounts. Add the numeric Hub IDs of the HubSpot portals (CRM accounts) that should be able to OAuth into the connector. The Hub ID appears in the URL when you browse the portal (app-eu1.hubspot.com/contacts/<HUB_ID>/...) or under Settings → Account.

Store the OAuth credentials in the central workspace secrets

Open the central hubspot workspace in the Prisme.ai Builder (Studio), go to Workspace settings → Secrets and set:

hubspotOauthClientId — the Client ID from the Auth tab of the deployed app
hubspotOauthClientSecret — the Client Secret matching it

These secrets are scoped to the hubspot workspace itself — they are NOT exposed to the end users or to any tenant who installs the app.

Declare the OAuth authentication in Governance

Open Prisme.ai Governance → Capabilities → HubSpot (or whichever capability your agents will use to consume the connector) and attach an authentication configuration that points at the three central webhooks of the hubspot workspace:

{
  "type": "oauth2",
  "status_url": "<api-url>/workspaces/slug:hubspot/webhooks/checkAuthStatus",
  "connect_url": "<api-url>/workspaces/slug:hubspot/webhooks/initiateOAuth",
  "disconnect_url": "<api-url>/workspaces/slug:hubspot/webhooks/disconnectOAuth"
}

Replace <api-url> with your environment’s API URL (https://api.studio.prisme.ai/v2 on production). Governance uses these URLs to (1) probe whether the calling user is already connected (status_url), (2) trigger the OAuth handshake when they are not (connect_url), and (3) revoke the session on demand (disconnect_url).

Grant the capability to the right roles

Still in Governance, grant the HubSpot capability to the roles or users who should be allowed to sign in with their own HubSpot account through the central MCP. Without this grant, central-mode callers get 401 Authentication required.

Test the flow

From an Agent Creator agent that has the HubSpot capability enabled, call any tool (e.g. contacts action=list). The agent receives a connect_url on the first call; opening it lets the user pick their HubSpot portal and authorize the requested scopes, then returns to a callback page that closes itself after 5 seconds. Subsequent tool calls reuse the stored access token transparently.

HubSpot scope handling has a strict OAuth-URL contract: the connector lists required scopes in scope= and optional scopes in optional_scope=, and every requested scope must already be declared in the HubSpot app’s requiredScopes or optionalScopes. Putting an optional-tier scope (Marketing Hub Pro+, CMS Hub, etc.) into scope= triggers a “domain mismatch” rejection. The shipped app-hsmeta.json keeps requiredScopes to the 9 free-tier essentials (oauth, contacts, companies, deals, owners, tickets); paid-tier scopes (lists, content, automation, forms, files, schemas, e-commerce) sit in optionalScopes. If you need to add a scope, edit BOTH sandbox/src/app/app-hsmeta.json AND prod/src/app/app-hsmeta.json, then re-run hs project upload && hs project deploy for each.

Error Handling

HTTP Status	Meaning	Typical Cause
`400`	Bad Request	Invalid property value, malformed `filterGroups`, missing required field
`401`	Unauthorized	Missing / invalid PAT or OAuth token, revoked refresh token
`403`	Forbidden	The token does not include the required scope, or the user/portal does not have the feature enabled (Marketing Hub Pro+, etc.)
`404`	Not Found	Record / list / workflow / form does not exist (or was archived)
`409`	Conflict	Unique-property collision (e.g. contact with the same email already exists)
`429`	Rate Limited	Per-portal quota exceeded — back off based on the `X-HubSpot-RateLimit-Secondly-Remaining` headers
`500` / `502` / `503`	Server Error	Transient HubSpot API error — retry with exponential backoff

Common Issues

“Authentication required: please sign in to Prisme.ai before calling the HubSpot MCP without an mcp-api-key header” — A caller hit the central endpoint without a valid Prisme.ai session AND without an mcp-api-key. Either sign in to Prisme.ai (central mode) or pass the tenant mcp-api-key (tenant mode). “Central OAuth config missing” — The hubspotOauthClientId / hubspotOauthClientSecret secrets of the central hubspot workspace are empty. Ask the platform admin to complete the Setup (one-time, platform admin) section above. “HubSpot capability not granted” — The current user is signed in to Prisme.ai but has not been granted the HubSpot capability in Governance. Ask the platform admin. “Invalid mcp-api-key” (tenant mode) — The mcp-api-key header does not match the central app secret. Reinstall the app instance to regenerate a signed key. “This HubSpot tenant has no Personal Access Token configured” — Tenant mode was used (mcp-api-key header present) but the app instance’s PAT field is empty. Either fill the token or drop the header to fall back to central OAuth. invalid_scope / “domain mismatch” during the OAuth dance — The OAuth URL requests a scope that the deployed HubSpot Public App does not declare. HubSpot OAuth requires scope= (mandatory) and optional_scope= (best-effort) to be split, and every requested scope to appear in either requiredScopes or optionalScopes of app-hsmeta.json. Edit both sandbox/src/app/app-hsmeta.json AND prod/src/app/app-hsmeta.json, then hs project upload && hs project deploy for each. redirect_uri_mismatch during the OAuth dance — The redirect URI generated by the connector (<api-url>/workspaces/slug:hubspot/webhooks/oauthCallback) is not in the deployed HubSpot app’s redirectUrls. Edit app-hsmeta.json and re-deploy. “The app could not be installed because the app developer has not signed the acceptable use policy” — Only happens with distribution: marketplace apps. The shipped projects use distribution: private to bypass this requirement (capped at 10 allowlisted portals). If you switch to marketplace later, sign the AUP from the HubSpot developer dashboard before the first install. MISSING_SCOPES (403) — The user’s portal subscription does not include the feature the operation needs (Marketing Hub Pro+, CMS Hub, etc.), or the user did not grant the corresponding optional scope. Some scopes are only available on paid HubSpot tiers — the connector keeps them in optionalScopes so they degrade gracefully on Free / Starter portals. OBJECT_ALREADY_EXISTS on contact create — A contact with the same email already exists. Either update the existing contact (use email as idProperty) or query first with search. Lists API: cannot add members to a dynamic list — Only static / MANUAL lists accept addMembers and removeMembers. Dynamic lists are managed by their filter criteria. Central OAuth — disconnecting a user — In central mode, the agent calls the disconnect tool (or the user opens <api-url>/workspaces/slug:hubspot/webhooks/disconnectOAuth) to delete the stored tokens. HubSpot does not expose an RFC 7009 revocation endpoint, so the refresh tokens may still be valid at HubSpot until they naturally expire (typically 6 months idle).

External Resources

HubSpot Developer Docs

Official HubSpot REST API reference

HubSpot Developer Platform 2025.2

Build, deploy and manage HubSpot Public Apps via the CLI Projects framework

HubSpot OAuth scopes

Required vs optional scopes, scope-tier matrix, scope group reference

Tool Agents

Build AI agents that call MCP tools dynamically

CRM Records

Engagements & Pipelines

Central OAuth or PAT

​Prerequisites

​Installation

​Configuration

​Available Instructions

​Contacts

​Companies

​Deals

​Tickets

​Associations

​Engagements

​Pipelines

​Properties

​Owners

​Lists

​Forms

​Marketing Emails

​Workflows

​Files

​DSUL Examples

​Look up a contact by email

​Create a deal and associate it to a company

​Add a contact to a static list

​Send a transactional email

​Bulk-import contacts

​Plug into an Agent Creator capability (central OAuth)

​Tenant PAT (shared token, no per-user sign-in)

​Legacy MCP install (Advanced → Tools)

​Output Formats

​Available Tools

​contacts / companies / deals

​tickets

​associations

​notes / tasks / calls / engagementEmails / meetings

​pipelines

​properties

​owners

​lists

​forms

​marketingEmails

​workflows

​files

​OAuth Session

​Tool Details

​contacts (action: search)

​deals (action: create)

​lists (action: addMembers)

​marketingEmails (action: sendTransactional)

​workflows (action: enrollContact)

​Error Handling

​Common Issues

​External Resources

HubSpot Developer Docs

HubSpot Developer Platform 2025.2

HubSpot OAuth scopes

Tool Agents

Prerequisites

Installation

Configuration

Available Instructions

Contacts

Companies

Deals

Tickets

Associations

Engagements

Pipelines

Properties

Owners

Lists

Forms

Marketing Emails

Workflows

Files

DSUL Examples

Look up a contact by email

Create a deal and associate it to a company

Add a contact to a static list

Send a transactional email

Bulk-import contacts

Plug into an Agent Creator capability (central OAuth)

Tenant PAT (shared token, no per-user sign-in)

Legacy MCP install (Advanced → Tools)

Output Formats

Available Tools

`contacts` / `companies` / `deals`

`tickets`

`associations`

`notes` / `tasks` / `calls` / `engagementEmails` / `meetings`

`pipelines`

`properties`

`owners`

`lists`

`forms`

`marketingEmails`

`workflows`

`files`

OAuth Session

Tool Details

`contacts` (action: `search`)

`deals` (action: `create`)

`lists` (action: `addMembers`)

`marketingEmails` (action: `sendTransactional`)

`workflows` (action: `enrollContact`)

Error Handling

Common Issues

External Resources