# HubSpot setup for PopMCP

You end up with one HubSpot access token (it looks like pat-na1-…) that you paste into PopMCP's "Private App access token" field.

- Auth: API credentials
- Setup time: 6 min
- API base URL: https://api.hubapi.com
- Credentials screen: https://app.hubspot.com/l/legacy-apps
- Provider docs: https://developers.hubspot.com/docs/guides/apps/private-apps/overview

## Before you begin

- A HubSpot account on any tier, including Free
- Super Admin permissions, because only Super Admins can see or create private apps and service keys
- A list of the data you want PopMCP to reach, since you tick the scopes yourself and a missing scope fails at call time
- Somewhere safe to store the token. It is revealed only behind a Show token click and is treated as a password

## Get your credentials

### 1. Open Legacy apps in HubSpot

In the main left sidebar click Development, then click Legacy apps.

Screen: https://app.hubspot.com/l/legacy-apps

### 2. Create a private app and name it

Click Create legacy app in the top right and choose Private. On the Basic Info tab, name the app `PopMCP`.

### 3. Grant the scopes PopMCP needs

Open the Scopes tab and search for the objects you want to reach. Tick at least `crm.objects.contacts.read` and `crm.objects.contacts.write`, plus a write scope for anything PopMCP should change.

Screen: https://app.hubspot.com/l/legacy-apps

### 4. Create the app and copy the access token

Click Create app in the top right, then Continue creating in the confirmation dialog. On the Auth tab click Show token, then Copy.

Screen: https://app.hubspot.com/l/legacy-apps

### 5. Paste the token into PopMCP

Open the HubSpot connector in PopMCP and paste the value into Private App access token. Click Connect.

## Fields PopMCP asks for

- Private App access token (accessToken) [required]: HubSpot → Settings → Integrations → Private Apps → (create or open an app) → Auth tab → Access token. Grant the scopes for the data you want the MCP to reach. Stored encrypted.

## Verify

PopMCP shows HubSpot as Connected with your Hub ID, and asking it for your five most recently created contacts returns real records instead of a scope error.

## Troubleshooting

### 401 Unauthorized on every call

Cause: The token was truncated on copy, or the private app was deleted or rotated after you pasted it.

Fix: Reopen the app's Auth tab, click Show token then Copy rather than selecting the masked text by hand, and re-paste it into PopMCP. HubSpot does not email or rotate the token on a schedule, so the same value stays valid until you rotate it.

### 403 with MISSING_SCOPES on some tools only

Cause: The token authenticated fine but the private app was never granted that object's scope.

Fix: Development → Legacy apps → your app → Scopes → Add new scope, tick the missing scope, then Update and Save. The existing token picks up the new scope with no re-copy needed.

### I cannot see Legacy apps or Private apps anywhere

Cause: You are not a Super Admin, or your account can no longer create legacy private apps. HubSpot is winding legacy private apps down in favour of account service keys.

Fix: Ask a Super Admin to create it, or use the replacement path: Development → Keys → Service keys → Create service key, add the same scopes, then Show and Copy. The resulting pat-na1 token works in the same PopMCP field.

### 429 Too Many Requests during a large sync

Cause: You hit the per-app burst limit of 100 to 190 requests per 10 seconds.

Fix: Let PopMCP retry, narrow the request, or add the API add-on to raise the ceiling to 200 requests per 10 seconds.

---

Source: https://www.docs.popmcp.com/docs/integrations/hubspot/