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

# HubSpot

> Connect HubSpot with OAuth so agents can search contacts, companies, deals, and tickets, and summarize your sales pipeline

Connect HubSpot and CloudThinker agents can look up contacts, companies, deals, and tickets, follow the links between them, and summarize a sales pipeline in plain language. The connection uses **OAuth** (you sign in to HubSpot and approve access), so there's no API key to create or paste. Agents run through HubSpot's hosted MCP server (Model Context Protocol, a standard way for agents to call a service's tools) and see only what the HubSpot user who authorizes can see.

## Prerequisites

* A **HubSpot account** you can sign in to, with access to the records agents should read.
* Permission to authorize apps in that HubSpot account. The first connection from a HubSpot account must be made by a HubSpot admin, by completing the steps below once. After that, other users in the account can connect.
* A browser that allows popups from CloudThinker, because HubSpot opens in a new window.
* The **Admin** role in your CloudThinker workspace, which can add and edit connections. See [Roles](https://docs.cloudthinker.io/guide/security/roles.md).

## Setup

**1. Open the HubSpot connection**

In the sidebar, click **More → Workspace settings → Connections**. On the **Builtin Connections** tab, search for **HubSpot** and click **Connect**.

**2. Sign in to HubSpot**

In the **Connect HubSpot** dialog, click **Open HubSpot**. HubSpot opens in a new window.

**3. Pick the account and grant access**

Select the HubSpot account to connect, review the permissions HubSpot lists, and authorize. HubSpot bases those permissions on your own HubSpot user.

**4. Return to CloudThinker**

The HubSpot window and the dialog close on their own once HubSpot confirms.

**Success state:** the HubSpot connection shows **Connected**.

## Connection details

There are no fields to fill in. CloudThinker stores the access and refresh tokens HubSpot issues and renews them without asking you again.

## Required permissions

HubSpot doesn't let you pick scopes by hand during OAuth. What agents can reach is set by two things:

| Control | What it decides |
| - | - |
| **The authorizing user's HubSpot permissions** | Agents can only view records that user can already view. They never see more. |
| **Sensitive Data properties** | Never exposed through this connection. |
| **Activity data** (calls, emails, meetings, notes, tasks, conversations) | Blocked by HubSpot when the account has Sensitive Data turned on in its HubSpot data management settings. |

> [!TIP]
>
> Authorize with a HubSpot user whose permissions cover only the records agents should see, for example a user limited to the Sales team's pipelines. CloudThinker can't narrow access below what that user has.

## Agent capabilities

| Capability | What agents can do |
| - | - |
| **Account details** | Show the connected HubSpot user, the account, and which CRM objects are available |
| **Contacts and companies** | Search by name, email, or domain and open a record with the properties you ask for |
| **Deals** | Search deals and report amount, stage, and close date |
| **Tickets** | Search support tickets and open one by ID |
| **Associations** | Follow links between records, such as a contact's company or a company's open deals |
| **Other CRM objects** | Read quotes, products, line items, orders, invoices, carts, and subscriptions where your HubSpot plan has them |

Reads run without asking. The tools come from HubSpot's MCP server, so HubSpot decides which ones exist. Any tool that changes CRM data counts as a write, and [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) decides whether it runs, waits for a person, or is refused.

### Verify the connection

```text theme={null}
Show which HubSpot account CloudThinker is connected to and which CRM objects I can read
```

A working connection names your HubSpot user and account and lists objects such as contacts, companies, and deals. An authentication error means the authorization expired or was revoked: reconnect.

### Example prompts

```text theme={null}
List open HubSpot deals closing this quarter with amount, stage, and close date
Find the HubSpot contact for buyer@example.com and the company they belong to
Summarize the last five HubSpot tickets for Example Corp and flag any still open
Which deals in the "Decision Maker Bought In" stage have no close date set?
```

> [!NOTE]
>
> Name the properties you need, such as amount or stage. A narrow request returns faster and keeps the answer focused.

## Troubleshooting

> [accordion] Popup blocked. Please allow popups for this site.
>
> Your browser blocked the HubSpot window. Allow popups for CloudThinker, then click **Open HubSpot** again.

> [accordion] HubSpot won't let me authorize
>
> No HubSpot admin has connected this HubSpot account yet. Ask a HubSpot admin to complete the setup above once, then try again with your own user.

> [accordion] Connection is taking longer than expected. Refresh to check its status.
>
> CloudThinker didn't see the authorization finish. Refresh the page and check the HubSpot connection. If it isn't **Connected**, start the connection again.

> [accordion] The provider rejected these credentials. Update them, then connect again.
>
> HubSpot refused the stored authorization, for example because it expired or someone revoked the app in HubSpot. Open the HubSpot connection, start the connection again, and re-authorize.

> [accordion] This connection did not respond in time. Try connecting again.
>
> HubSpot didn't answer in time. Wait a moment and connect again.

> [accordion] Agents can't see a record or a type of data
>
> The authorizing user's HubSpot permissions decide what's visible, and some objects depend on your HubSpot subscription. Check that the user can open the record in HubSpot. If Sensitive Data is on, activity data such as emails and notes is blocked by HubSpot. HubSpot grants new scopes only when you authorize again. If a capability listed above is missing, open **HubSpot** in **More → Workspace settings → Connections**, click the trash icon (**Disconnect**) on the account's row, and connect again.

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Authorize as the right user.** The connection acts with that user's HubSpot permissions, so pick an account that only reaches what agents need.
- **Revoke from either side.** In CloudThinker, click the trash icon (**Disconnect**) on the account's row. In HubSpot, open **Settings → Integrations → Connected Apps** and uninstall the app.

## Related

> [card] [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md)
>
> Decide which changes run, wait for a person, or are refused

> [card] [Connections](https://docs.cloudthinker.io/guide/connections/overview.md)
>
> Every service you can connect to CloudThinker


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