> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnifact.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up HubSpot

> Connect HubSpot CRM to Omnifact via MCP: install the integration, choose between one-click setup or your own HubSpot OAuth app, configure tool approval policies, and link user accounts.

Connecting **HubSpot CRM** to Omnifact via the **Model Context Protocol (MCP)** gives your sales, account management, customer support, and marketing teams live CRM context directly in chat. Your team can pull one-minute pre-call briefings across contacts, companies, deals, and tickets, search HubSpot inbox conversations, and log call notes or update deal stages without clicking through multiple record screens.

## How HubSpot Setup Works at a Glance

HubSpot connects as an OAuth-backed MCP integration across three steps:

> [card] 1. Organization Admin
>
> Installs **HubSpot** once from **Team Settings > Integrations > Catalog** and reviews per-tool execution policies (**Always**, **Approval**, or **Disable**).

> [card] 2. Team Members
>
> Sign in with their own personal HubSpot account under **Account Settings > App Connections** so HubSpot permissions stay enforced per user.

> [card] 3. In Chat
>
> The agent (An AI system that helps you with tasks through conversation and can take actions on your behalf) queries live CRM records on demand and asks for confirmation in chat before creating or updating any HubSpot record.

***

## Step 1: Install HubSpot for Your Organization (Admin)

An organization **Owner** or **Admin** adds the HubSpot integration once in Team Settings.

**1. Open the Integrations Catalog**

Click your **User Avatar** in the bottom-left corner, go to **[Team Settings > Integrations](https://docs.omnifact.ai/en/platform/team-administration/integrations.md)**, and open the **Catalog** tab.

**2. Select HubSpot**

Filter by **Sales & Service** (or search for `HubSpot`) and click **Add** on the **HubSpot** card.

**3. Choose Automatic Setup or Your Own HubSpot OAuth App**

In the **Add integration** dialog, review the connection summary (`https://mcp.hubspot.com`) and choose how users will authenticate:

* **Automatic setup (Omnifact Cloud default):** Omnifact provides a pre-configured HubSpot OAuth app so you can connect in one click without registering an app in HubSpot.
* **Use your own OAuth app (Optional or self-hosted):** If your organization prefers to authenticate through its own registered HubSpot app, click **Use your own OAuth app**, register the displayed **Redirect URI** (`https://chat.omnifact.ai/oauth/mcp-callback`) in your HubSpot developer account, and enter your **Client ID** and **Client secret**. See [Registering Your Own OAuth Client](https://docs.omnifact.ai/en/platform/team-administration/mcp-servers.md#registering-your-own-oauth-client-custom-credentials) for details.

**4. Sign In and Discover Tools**

Click **Sign in with HubSpot**. In the HubSpot popup window, sign in with your HubSpot account, select your HubSpot portal, and grant access.

Omnifact validates the connection, discovers the available HubSpot tools, and redirects you to the HubSpot server details page under **Team Settings > Integrations > Installed**.

![The Integrations Catalog tab in Team Settings showing category filters, search, and curated integration cards.](https://mintcdn.com/omnifact/tRH9Gi0LEITIC1Eu/images/Documentation/settings-integrations-catalog-en.png?fit=max\&auto=format\&n=tRH9Gi0LEITIC1Eu\&q=85\&s=4c194ec1d5a3a83a3653e3b9d0d9e6b4)

***

## Step 2: Review Tool Access Policies (Admin)

After installing HubSpot, you land directly on its tool governance page. Every tool exposed by the HubSpot MCP server operates under one of three execution policies:

* **Always:** Safe, read-only lookups (such as searching contacts, reading companies, viewing deal pipelines, or listing tickets) run autonomously without interrupting the user.
* **Approval:** State-changing operations (such as creating or updating contacts, advancing deal stages, or logging call notes and tasks) pause generation and display an interactive confirmation banner in chat before writing to HubSpot.
* **Disable:** Hides the tool completely so AI models cannot see or invoke it.

> [!TIP]
>
> **Recommended governance:** Keep read-only HubSpot lookup tools on **Always** for fast briefings, keep all write/update tools on **Approval** so users review every CRM change before it is saved, and set any tools your organization does not use to **Disable**.

> [!WARNING]
>
> **Privacy Filter Boundary for MCP Servers:** Tool calls to external MCP servers (`https://mcp.hubspot.com`) **bypass the Privacy Filter (A system that automatically detects and masks supported sensitive information before it reaches AI models) in both directions**. Arguments sent to HubSpot (such as a contact's real name, email address, or deal ID) go out unfiltered so HubSpot can find the record, and CRM results return unfiltered into the conversation.

***

## Step 3: Connect Your Personal HubSpot Account (All Users)

Installing HubSpot in Team Settings makes the integration available to your workspace, but **tools are not active for individual users until they connect their own HubSpot account**. Because each person signs in individually, the agent only sees and updates the contacts, companies, deals, and tickets that user's HubSpot role allows.

**1. Open App Connections**

Click your **User Avatar** in the bottom-left corner, select **Account Settings**, and open **[App Connections](https://docs.omnifact.ai/en/platform/core-features/account-settings/connections.md)** (or go directly to `https://chat.omnifact.ai/account/connections`).

**2. Connect HubSpot Under MCP Servers**

Scroll down to the **MCP Servers** section, find **HubSpot**, and click **Connect**.

**3. Select Your HubSpot Portal and Authorize**

Sign in to HubSpot in the popup window, select your organization's HubSpot account, and approve the requested permissions. The HubSpot card now displays a **Connected** badge.

![App Connections page in Account Settings where team members connect their personal accounts.](https://mintcdn.com/omnifact/eFN-x5hJg72gP6In/images/user-settings-connections.png?fit=max\&auto=format\&n=eFN-x5hJg72gP6In\&q=85\&s=c963c54c2176ecf3f1466d6ae9c63930)

> [!NOTE]
>
> **In-chat onboarding hint:** If a team member asks the agent to look up or update HubSpot records before linking their account (or after their session expires), the agent automatically prompts them in chat to connect HubSpot under **Account Settings > App Connections**.

***

## Step 4: Using HubSpot in Chat & Approving CRM Updates

Once your HubSpot account is connected, simply mention HubSpot or your CRM records in any chat or Space (A dedicated environment with a specialized agent and optional Uploaded Files):

> [card] Prepare a Pre-Call Briefing
>
> *"Prepare a pre-call briefing for Acme GmbH from HubSpot: list the associated contacts, open deals with their current stage and amount, open support tickets, and a summary of the last 3 notes or emails."*

> [card] Log Call Notes & Follow-Ups
>
> *"Here are my rough notes from the Acme GmbH call. Log them as a note on the deal in HubSpot, create a follow-up task for Friday, and move the deal stage to Decision Maker Bought-In."*

> [card] Inspect Pipeline & Deals
>
> *"Show all open HubSpot deals closing this quarter over €20,000, grouped by pipeline stage, and flag any deal with no activity in the past 14 days."*

> [card] Review Tickets & Conversations
>
> *"List all open HubSpot support tickets for Acme GmbH and check how they relate to their active renewal deal."*

### Confirming CRM Changes in Chat

Whenever the agent invokes a HubSpot tool configured with the **Approval** policy:

1. Response generation pauses and an interactive **Tool Approval Banner** appears directly above the chat input.
2. You can expand the banner to inspect the exact HubSpot tool name and field values being sent.
3. Click **Allow** to execute the update in HubSpot, or **Deny** to cancel the action without modifying any CRM data.

![Interactive Tool Approval Banner above the chat input with Deny and Allow buttons.](https://mintcdn.com/omnifact/vLeigdfrLhBPb253/images/Documentation/feature-drop-mcp-servers-approval.png?fit=max\&auto=format\&n=vLeigdfrLhBPb253\&q=85\&s=c4b7f83b343979102f544c1dfcf998ea)

***

## Common Questions & Troubleshooting

> [accordion] Why does the agent say it cannot access HubSpot?
>
> Check two places:
>
> 1. **Personal connection:** Open **[Account Settings > App Connections](https://docs.omnifact.ai/en/platform/core-features/account-settings/connections.md)** and verify that **HubSpot** under **MCP Servers** shows **Connected**. If it shows **Reconnect required**, click **Reconnect**.
> 2. **Tool policy:** Ask an administrator to check **Team Settings > Integrations > Installed > HubSpot** to ensure the required HubSpot tools are set to **Always** or **Approval** rather than **Disable**.

> [accordion] Which HubSpot records can colleagues see through Omnifact?
>
> Only the contacts, companies, deals, tickets, and campaigns that **their own HubSpot user account** is permitted to view. Omnifact never uses a shared admin API key for catalog OAuth integrations, so HubSpot team-level and owner-level permissions remain strictly enforced.

> [accordion] Does Omnifact copy or index our entire HubSpot database?
>
> No. Unlike [Connected Sources](https://docs.omnifact.ai/en/platform/core-features/spaces/connected-sources.md) for cloud storage, HubSpot MCP tools query live records on demand only when your conversation requires them. Your CRM database stays in HubSpot.

> [accordion] How do we switch from automatic setup to our own HubSpot OAuth app later?
>
> An administrator can open **Team Settings > Integrations > Installed > HubSpot**, click **Edit**, click **Use your own OAuth app**, enter the organization's **Client ID** and **Client secret** (with `https://chat.omnifact.ai/oauth/mcp-callback` registered as the redirect URI in HubSpot), and click **Connect & Save**.

## Related Resources

> [card] [MCP Servers](https://docs.omnifact.ai/en/platform/team-administration/mcp-servers.md)
>
> Deep dive into MCP server setup, custom OAuth client registration, and per-tool governance.

> [card] [App Connections](https://docs.omnifact.ai/en/platform/core-features/account-settings/connections.md)
>
> How users connect, reconnect, and manage their personal tool accounts.

> [card] [Integrations Administration](https://docs.omnifact.ai/en/platform/team-administration/integrations.md)
>
> Explore all 35+ connectors in the Integrations Catalog.

> [card] [Setting Up SharePoint](https://docs.omnifact.ai/en/guides/connections-setup/sharepoint.md)
>
> Connect Microsoft SharePoint to sync document libraries into Spaces and attach files in chat.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.