# Connect an AI agent to HubSpot: MCP or REST for company write-back

Enrichment Desk. A ZeroClick publication (https://enrichmentdesk.com/about/). Published 2026-11-03.
Format: Guide. Topic: Pipeline and CRM (https://enrichmentdesk.com/topics/pipeline-and-crm/).
Canonical: https://enrichmentdesk.com/articles/connect-ai-agent-to-hubspot/

MCP is the obvious way to give an agent your CRM, and since April 2026 HubSpot's [remote MCP server](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server) can update company records. For enrichment there's a catch. Before its write tool creates or updates anything, it shows a summary of the proposed changes and waits for a person to confirm. That works when someone is watching the agent. It fails for a nightly job writing fresh company data back to thousands of records, with nobody there to say yes.

For that job, use HubSpot's [REST batch update endpoint](https://developers.hubspot.com/docs/api-reference/latest/crm/objects/companies/batch/update-companies) with a [service key](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys). It takes up to 100 companies per request, with no confirmation step, and it can't create a company by accident, because update only changes records that already exist. You need each company's HubSpot record ID and a key with company read and write scopes. If the job needs webhooks, use an app instead; if it runs across several HubSpot accounts, use OAuth. Every step below follows HubSpot's documentation.

## How to write enrichment results back to HubSpot companies

1. **Create a service key** under Development > Keys > Service keys, with the scopes `crm.objects.companies.read` and `crm.objects.companies.write`. Load it from a secret store when the job starts and send it as a Bearer token, so it never appears in a prompt or a log line.
2. **Start from record IDs.** Keep the HubSpot record ID from the matching step for every company. Our guide to [getting a company name from a domain](https://enrichmentdesk.com/articles/domain-to-company-name/) covers the match itself.
3. **Read before you write.** [Batch-read](https://developers.hubspot.com/docs/api-reference/latest/crm/using-object-apis) the current values of every field the job may change, up to 100 records per request. Use the `2026-09` API version here and in every later call.
4. **Decide what to change.** Validate each proposed value outside the writer, against the rules in our guide to [match rate, fill rate and freshness](https://enrichmentdesk.com/articles/match-rate-fill-rate-freshness-enrichment-api/), and drop every field that would not change. Then apply a field allowlist and an overwrite policy: for example, fill empty fields and never overwrite a value a person entered.
5. **Write in batches of 100.** Send the remaining changes to `POST /crm/objects/2026-09/companies/batch/update` in chunks of at most 100 inputs. Use batch update, not batch upsert, because upsert creates any record it does not find.
6. **Check and read back.** Check every result, then read the changed fields back with the same batch read and compare them with what you sent.

## Example calls

Every request carries the service key as a Bearer token, in the form HubSpot's own example uses. The batch read asks for the current values of the fields the job may touch. The path takes the object's name, `companies`, or its object type ID, `0-2`.

```http
POST https://api.hubapi.com/crm/objects/2026-09/companies/batch/read
Authorization: Bearer <service key>
Content-Type: application/json

{
  "properties": ["name", "domain", "<your_field>"],
  "inputs": [{"id": "<record ID 1>"}, {"id": "<record ID 2>"}]
}
```

The update carries only the fields that survived the comparison and the overwrite policy. The endpoint accepts an `objectWriteTraceId` on each input and returns it with each result, which ties every result to the change that produced it.

```http
POST https://api.hubapi.com/crm/objects/2026-09/companies/batch/update
Authorization: Bearer <service key>
Content-Type: application/json

{
  "inputs": [
    {"id": "<record ID 1>", "properties": {"domain": "example.com"},
     "objectWriteTraceId": "run-01-0001"},
    {"id": "<record ID 2>", "properties": {"<your_field>": "<new value>"},
     "objectWriteTraceId": "run-01-0002"}
  ]
}
```

HubSpot documents a 200 response and a 207 response for mixed results; the 207 adds `numErrors` and an `errors` list. Trimmed, with placeholders:

```json
{
  "status": "COMPLETE",
  "results": [
    {"id": "<string>", "objectWriteTraceId": "<string>",
     "properties": {}, "updatedAt": "<date-time>"}
  ],
  "numErrors": 1,
  "errors": [
    {"status": "<string>", "category": "<string>", "message": "<string>", "context": {}}
  ]
}
```

What to do with each result:

- **A batch that is not `COMPLETE`.** The response's `status` can also be `PENDING`, `PROCESSING` or `CANCELED`. HubSpot gives `COMPLETE` as the expected value, so treat anything else as a batch to recheck.
- **Partial failures.** A 207 means some inputs succeeded and some failed. Match results by `objectWriteTraceId` and retry only the failed inputs.
- **423 Locked.** HubSpot returns it when an account syncs a large volume of data in a short time, and asks for a delay of at least 2 seconds between requests.
- **429 Too many requests.** The job is over its rate limit. Slow down and resend.
- **Validation errors.** A value HubSpot rejects will be rejected again. Queue it for a person instead of retrying.

## What it costs

HubSpot's [usage guidelines](https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines) publish limits, not a per-call price. They set an app's allowance by the subscription of the account it runs in, and by whether that account has bought the API limit increase. Service keys have the same limits as privately distributed apps. The burst limit applies to each app, and the daily limit is shared across the account.

| Account tier | Burst, per app | Daily, per account |
|---|---|---|
| Free and Starter | 100 per 10 seconds | 250,000 |
| Professional | 190 per 10 seconds | 625,000 |
| Enterprise | 190 per 10 seconds | 1,000,000 |
| With API limit increase | 250 per 10 seconds | +1,000,000 per increase, up to two |

The recipe above makes three calls per 100 companies: one read, one update and one read-back. At that rate, ten thousand companies take 300 calls, about a tenth of a percent of the smallest daily limit. That makes the burst limit the one to pace against, and retries add to the count.

## When this is the wrong tool

A service key only makes REST requests: it cannot authenticate webhooks or make calls within a UI extension, and an app distributed to more than one account must use OAuth. Here are all four ways in, side by side.

| Way in | Access and how it is granted | Who sets it up | Rate limit | Token lifetime and refresh | What it cannot do |
|---|---|---|---|---|---|
| Remote MCP server, through an MCP connector | The acting user's HubSpot permissions, granted at OAuth sign-in with PKCE; you do not pick scopes | Created under Development > MCP Connectors | Not published in its guide | Not published in its guide; the client renews with its refresh token, or signs in again | Write without a person confirming each create or update; reach activity and conversation data when Sensitive Data is on |
| Service key | Object scopes you pick, such as `crm.objects.companies.read` and `crm.objects.companies.write` | Super admins, or users granted the Developer tools access permission | Privately distributed app limits | Rotated by hand (the old key expires at once or in 7 days) or automatically every 3, 6 or 12 months | Authenticate webhooks, call from a UI extension, or do anything beyond REST requests |
| Projects app, static auth | REST scopes you pick (required scopes only), plus app features such as webhooks and UI extensions | [Installed](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot) by super admins or users with HubSpot Marketplace access plus the scopes' permissions | Privately distributed app limits | Static token; HubSpot recommends rotating it every 6 months; reinstall after a scope change | Be installed in more than one standard account at a time |
| [OAuth app](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/overview) | Required, conditionally required and optional scopes, granted at install | The same installers; you host the OAuth backend | Private: privately distributed limits; Marketplace: 110 requests per 10 seconds per installing account | [Access token lasts 30 minutes](https://developers.hubspot.com/docs/api-reference/latest/authentication/manage-oauth-tokens); the refresh token gets a new one | Run without a hosted OAuth backend; exceed 10 allowlisted accounts on private distribution |

HubSpot caps each account at 100 project-based apps, service keys and MCP connectors combined. That cap limits how many you can create. It is not a limit on requests or on batch size.

### Three things HubSpot calls MCP

HubSpot uses the name MCP for three different things, and they point in different directions. The remote HubSpot MCP server connects an outside agent to an account's CRM data, and it is the only one of the three this guide needs. It became [generally available on April 13, 2026](https://developers.hubspot.com/changelog/remote-hubspot-mcp-server-is-now-generally-available), when HubSpot added write access, companies included.

The local Developer MCP server helps coding agents build HubSpot apps and CMS assets. It has been [generally available since February 19, 2026](https://developers.hubspot.com/changelog/hubspot-developer-mcp-server-for-app-and-cms-development-now-in-ga).

The [MCP server app component](https://developers.hubspot.com/docs/apps/developer-platform/add-features/mcp-server), in public beta, runs the other way: it lets HubSpot's own agents call an external MCP server. Separately, HubSpot's [Agent CLI](https://knowledge.hubspot.com/integrations/use-the-hubspot-agent-cli) is a newer route that connects coding agents to an account.

### Supervised edits through MCP

When a person is watching, MCP is the better fit: the agent proposes each change and the person approves it. The client has to complete HubSpot's OAuth sign-in with PKCE, a check that proves the app finishing the sign-in is the one that started it, and listing MCP support doesn't guarantee that. HubSpot's guide says the MCP Inspector handles PKCE automatically, and [Cursor's docs](https://prod.cursor.com/docs/mcp) say its sign-in uses the authorization code flow with PKCE. In Claude, use HubSpot's [connector for Claude](https://knowledge.hubspot.com/integrations/set-up-and-use-the-hubspot-connector-for-claude), where HubSpot recommends setting Write tools to Needs Approval.

### If you planned on a private app

HubSpot [disabled creating legacy private apps](https://developers.hubspot.com/changelog/legacy-private-app-creation-sunset) on October 26, 2026 for existing accounts, and on September 28, 2026 for accounts created from that date. Existing legacy private apps keep working, and HubSpot points anyone needing the same thing to service keys.

## Frequently asked questions

### Can HubSpot's MCP server write to companies?

Yes. Since it became generally available on April 13, 2026, the remote HubSpot MCP server can create and edit companies and other CRM records, within the acting user's HubSpot permissions.

### Does HubSpot MCP need confirmation for every update?

Yes. Its `manage_crm_objects` tool presents a proposed-changes summary and requires explicit user confirmation before any create or update, which suits supervised edits rather than scheduled jobs.

### Should an AI agent use a service key or a private app?

For a REST-only job in one account, a service key. HubSpot disabled creating legacy private apps in existing accounts on October 26, 2026 and points to service keys instead; existing legacy private apps keep working. A Projects app is the choice when the job needs webhooks.

### How many companies can one HubSpot batch update change?

Up to 100. HubSpot caps each object API batch request at 100 inputs, so a larger write-back goes out in chunks.
