# Connecting an AI Agent to HubSpot: API, MCP and Breeze

> Your own AI agent reaches HubSpot through the REST API, using a service key or an app on the developer platform, or through HubSpot's official MCP server at mcp.hubspot.com. Breeze is HubSpot's built-in agent layer and fits when you need neither your own model nor your own logic.

Canonical URL: https://www.ruebstudio.de/en/guides/ai-agent-integrations/connect-ai-agent-hubspot  
Author: Dr.-Ing. Marcus Rüb, CEO  
Published: 2026-11-03

For many sales and service teams, HubSpot is where contacts, companies, deals and tickets live. An AI agent that prepares meetings, logs call notes or keeps deals tidy therefore needs read access to that CRM, and often write access too. There are three routes: the REST API, HubSpot's official MCP server, and HubSpot's own agents, sold under the Breeze name. Everything below is based on HubSpot's documentation as of November 2026.

## What does connecting an AI agent to HubSpot actually involve?

It means the agent can search, read, create and update HubSpot records through a small set of tools with tightly scoped permissions. It works on live CRM data rather than an export.

Common jobs that need this kind of access:

- **Before a meeting:** pull together the contacts, open deals, recent emails and notes for one account.
- **After a call:** turn a transcript into a note on the contact, create a follow-up task and suggest the next deal stage.
- **Data hygiene:** flag duplicates, report deals with missing required fields, find contacts with no company attached.
- **Support:** give a service rep the customer's history and similar tickets when a new ticket arrives.

This differs from a classic integration. A sync tool moves fixed fields on a fixed schedule. An agent decides at run time which data it needs and may combine HubSpot with other systems. That flexibility is useful, but it also means permissions and write access need firmer limits.

## How does access work? The building blocks

Every option rests on four building blocks: authentication, CRM objects and their properties, associations between records, and API limits. Once these are clear, the three routes become easy to compare.

### Authentication has changed in 2026

The most important change for anyone following older tutorials: according to [HubSpot's page on legacy private apps](https://developers.hubspot.com/docs/apps/legacy-apps/private-apps/overview), they can no longer be created as of 26 October 2026. Existing private apps still work but receive no new features.

New integrations have two options:

- **Service keys.** Created by super admins or users with the developer tools permission, a service key carries object-level scopes such as `crm.objects.contacts.read` and is sent as a bearer token in the `Authorization` header. [HubSpot's service key documentation](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys) notes they support REST calls only, not webhooks, and can rotate automatically every 3, 6 or 12 months.
- **Developer platform apps.** Versions 2025.2, 2026.03 and 2026.09 are created and deployed with the HubSpot CLI (`hs project create`), as described in the [build apps overview](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/overview). They use a static token or OAuth and are what you need for webhooks and other platform features.

For an agent working in a single HubSpot account, a service key is the quickest start. If the agent should react to events, such as a new deal or a changed ticket status, build an app with webhook subscriptions instead.

### Objects and properties

HubSpot models everything as objects: contacts, companies, deals and tickets; activities such as notes, tasks, calls and meetings; and any custom objects you define. Each object has properties. The agent can only use a property well if it knows what the values mean. A custom field called "quote status" with five internal codes is noise to a model unless you describe those codes in the tool definition or system prompt.

### Associations link the records

Associations connect records: a contact to its company, a deal to the people involved. [HubSpot's associations guide](https://developers.hubspot.com/docs/api-reference/crm-associations-v4/guide) distinguishes unlabelled default links, HubSpot-defined labels such as "Primary company" and custom labels such as "Decision maker". Each direction has its own type ID: contact to company is `279`, contact to primary company is `1`, deal to contact is `3`, contact to deal is `4`.

This is where many agents go wrong. A note created without associations does not appear on any timeline, so nobody sees it. Make your "create note" tool attach the note to the contact and deal in the same call, rather than trusting the model to remember a second step. Batch endpoints accept up to 1,000 inputs for reads and up to 2,000 for creates.

### Search, limits and API versions

Search is the tool an agent uses most, and it has tight limits. [HubSpot's search guide](https://developers.hubspot.com/docs/api-reference/search/guide) lists five requests per second per account, up to 200 results per page, a ceiling of 10,000 results per query, and at most five filter groups with 18 filters in total. Newly created or updated records take a moment to appear in results.

General limits for privately distributed apps are in the [usage guidelines](https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines): 100 requests per 10 seconds on Free and Starter, 190 on Professional and Enterprise, plus daily caps per account. Going over returns HTTP `429` with `errorType: "RATE_LIMIT"`.

Since March 2026 HubSpot versions its APIs by date. The [changelog announcement](https://developers.hubspot.com/changelog/introducing-date-based-api-versioning) explains that new versions ship in March and September, each is supported for at least 18 months, and the v4 APIs lose support in March 2027. Build new tools against `/2026-09/` from the start.

A minimal search tool for an agent, written in Python 3 with the `requests` library and following the endpoint format in the search guide:

```python
import os
import requests

BASE = "https://api.hubapi.com/crm/objects/2026-09"
HEADERS = {"Authorization": f"Bearer {os.environ['HUBSPOT_SERVICE_KEY']}"}

def deals_for_company(company_id: str) -> list[dict]:
    """Agent tool: deals associated with one company."""
    body = {
        "filterGroups": [{
            "filters": [
                {"propertyName": "associations.company", "operator": "EQ", "value": company_id},
            ]
        }],
        "properties": ["dealname", "dealstage", "amount", "closedate"],
        "limit": 50,
    }
    r = requests.post(f"{BASE}/deals/search", json=body, headers=HEADERS, timeout=20)
    r.raise_for_status()
    return [d["properties"] for d in r.json().get("results", [])]
```

The agent then reads `dealstage` to separate open from closed deals. The tool returns a fixed list of fields. That keeps the model's context small and stops sensitive properties from reaching the model by accident.

## Which route fits? Custom API tools, MCP and Breeze

The three routes differ in who writes the tools, which model does the reasoning and how finely you control access. Custom API tools give the most control, the MCP server the fastest setup, and Breeze the least engineering effort.

| Criterion | Custom API tools | HubSpot MCP server | Breeze agents |
|---|---|---|---|
| Who builds the tools | You | HubSpot | HubSpot |
| Model | Your choice | Any MCP client | HubSpot's |
| Permissions | Key scopes | Installing user | HubSpot roles |
| Other systems | Yes | Via other MCP servers | Limited |
| Hosting | Yours | HubSpot | HubSpot |

### Route 1: your own tools on the REST API

You write functions such as "find open deals for a company" or "create a note and link it", then expose them to the agent. It takes the most work, and gives you full control over which fields are read, which writes are allowed and what gets logged. The pattern is the same as for other systems, covered in [connecting AI agents to business systems](https://www.ruebstudio.de/en/guides/ai-agent-integrations/connect-ai-agents-to-business-systems). Choose this route when the agent must combine HubSpot with an ERP, a ticketing system or a file store, or when the model has to run on your own infrastructure or with a specific provider.

### Route 2: HubSpot's official MCP server

HubSpot hosts a remote MCP server at `https://mcp.hubspot.com`. According to [HubSpot's MCP integration guide](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-hubspot-mcp-server), you create an MCP connector under Development in your HubSpot account, which gives you a client ID and secret, and the MCP client handles OAuth. PKCE is mandatory. You do not set scopes yourself; access follows the permissions of whoever installs the connector.

The server can read CRM records, activities, marketing content and conversations, and can write CRM records, activities, pipelines and custom properties, among others. Revenue objects such as quotes and invoices are in beta. The guide also lists limits: the query tool has no joins or association traversal, and when sensitive data settings are on, conversations and activities are blocked.

For how MCP servers work in general and how to vet third-party ones, see the guide to [MCP servers for AI agents](https://www.ruebstudio.de/en/guides/ai-agent-integrations/mcp-servers-connect-ai-agents).

Do not confuse this with the **developer MCP server**, which the HubSpot CLI runs locally via `hs mcp setup`. The [HubSpot MCP overview](https://developers.hubspot.com/mcp) describes it as a helper for coding assistants that build apps and CMS assets, not as a route to CRM data.

### Route 3: Breeze, HubSpot's built-in agents

Breeze is the AI layer inside HubSpot. The [HubSpot AI product page](https://www.hubspot.com/products/artificial-intelligence) lists a Prospecting Agent, a Customer Agent, a Data Agent and an Agent Builder for custom agents on HubSpot data, among others. The [HubSpot Knowledge Base](https://knowledge.hubspot.com/ai/understand-breeze) explains that agents are managed in Agent Hub and consume HubSpot Credits, and that some require Professional or Enterprise subscriptions.

Breeze fits when the job sits entirely inside HubSpot and you do not need your own logic or model. A custom agent fits when it must pull in data from outside HubSpot, when you want to choose the model, or when workflows across several systems must be versioned and audited. The two can coexist: Breeze handling service chat, a custom agent preparing quotes from ERP data.

## What do you need in place first?

Three things: reasonably clean CRM data, someone with admin or developer rights in HubSpot, and a written decision about what the agent may change. Without these, an agent creates more clean-up work than it removes.

**Data.** Are contacts linked to companies? How many duplicates are there? Are deal stages and required fields used consistently? An agent can only be as reliable as the associations and properties it reads.

**Permissions.** Service keys are created by super admins or developer tools users. With the MCP server, the agent inherits the installing user's rights. A dedicated technical user with a narrow role is safer than a senior manager's account with full access.

**Ownership.** Decide who reviews the agent's output, who handles errors and which fields only humans may change, such as deal amount or close date. If personal data goes to an external model, that is a data protection question. Such a setup can be operated in line with the GDPR, but it needs a data processing agreement, a retention plan and logging. This is orientation, not legal advice.

## How do you roll it out step by step?

Start read-only with one narrow workflow, check quality against real cases, and only then grant write access field by field. That keeps each stage easy to review and easy to roll back.

1. **Pick one workflow** with a clear start and end, for example "meeting brief for existing accounts".
2. **Define the data:** which objects, which properties, which associations. Leave everything else out.
3. **Create access:** a service key with read-only scopes, or an MCP connector installed by a technical user.
4. **Build or select tools:** fixed field lists for custom API tools, or only the tools you need enabled in the MCP client.
5. **Test on real cases:** run ten to twenty actual situations and compare the output with what an experienced colleague would produce.
6. **Add writes gradually:** notes and tasks first, since they harm nobody; deal fields later, always with an audit log.
7. **Operate it:** watch errors and `429` responses, rotate keys, and move to a new API version before the old one loses support.

## What are the limits and risks?

The main risks are wrong writes, overly broad permissions and hostile content inside the CRM. On top of that come technical limits in search and API versioning that any agent in daily use will eventually hit.

- **Prompt injection through CRM content.** Emails, form submissions and notes often come from outside. If one contains an instruction aimed at "the AI", an agent may follow it (see [prompt injection](https://www.ruebstudio.de/en/glossary/prompt-injection)). Write tools need hard limits in code, not just in the prompt.
- **Overly broad access.** With the MCP server the agent has the installing user's rights. If a super admin installs it, the agent can do almost anything.
- **Search delay.** An agent that creates a contact and searches for it straight away may not find it and create a duplicate. Use the ID returned by the create call instead.
- **Volume ceilings.** Five search requests per second and 10,000 results per query are fine for single cases, not for analysing the whole database. Use exports or a data warehouse for that.
- **Platform churn.** Legacy private apps are frozen and v4 APIs expire in March 2027. Budget for maintenance.
- **When it is the wrong tool.** If the CRM is poorly maintained or the process itself is unclear, an agent will not fix it; it will only make the gaps visible.

## How do you get started?

Create a read-only service key and build a single tool, such as the deal search above, or connect an MCP-capable client to HubSpot's MCP server to explore your data. The first real cases will show which data is missing and which write permissions are worth granting.

In our own operations, the pattern that works is to let the agent draft suggestions that a person accepts, before it writes anything directly. The [AI sales agent guide](https://www.ruebstudio.de/en/guides/ai-agents-by-department/ai-sales-agent-guide) covers which sales tasks suit an agent. If your sales team runs on Microsoft rather than HubSpot, the main differences are authentication and the data model, as described in [connecting an AI agent to Dynamics 365](https://www.ruebstudio.de/en/guides/ai-agent-integrations/connect-ai-agent-dynamics-365). For how such agents are structured in sales, see the page on the [sales agent](https://www.ruebstudio.de/en/ai-agents/sales), and for the wider picture, the overview of [AI agents for business processes](https://www.ruebstudio.de/en/ai-agents). If the model and data must stay on your own infrastructure, read about [sovereign AI](https://www.ruebstudio.de/en/sovereign-ai).

## Frequently asked questions

### Can I still create a legacy private app in HubSpot?

No. HubSpot's documentation states that legacy private apps can no longer be created as of 26 October 2026, although existing ones keep working. New integrations should use a service key or a developer platform app.

### Do I have to host the HubSpot MCP server myself?

No. HubSpot runs it at mcp.hubspot.com. You create an MCP connector in your account, and your MCP client handles the OAuth sign-in, which requires PKCE.

### When is Breeze enough on its own?

When the task lives entirely inside HubSpot and the built-in agents cover it. Once the agent needs data from an ERP, a ticketing tool or a document store, or a model of your choice, a custom agent is the more flexible option.

### Which API version should a new integration target?

HubSpot advises using the latest date-based version, currently /2026-09/. The v4 APIs are only supported until March 2027.

## Sources

- [HubSpot Developers: Legacy private apps](https://developers.hubspot.com/docs/apps/legacy-apps/private-apps/overview)
- [HubSpot Developers: Service keys](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys)
- [HubSpot Developers: Build apps overview](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/overview)
- [HubSpot Developers: Integrate with the HubSpot MCP server](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-hubspot-mcp-server)
- [HubSpot Developers: MCP](https://developers.hubspot.com/mcp)
- [HubSpot Developers: Associations guide](https://developers.hubspot.com/docs/api-reference/crm-associations-v4/guide)
- [HubSpot Developers: CRM search guide](https://developers.hubspot.com/docs/api-reference/search/guide)
- [HubSpot Developers: API usage guidelines and limits](https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines)
- [HubSpot Developer Changelog: Introducing date-based API versioning](https://developers.hubspot.com/changelog/introducing-date-based-api-versioning)
- [HubSpot Knowledge Base: Agent Hub and agents](https://knowledge.hubspot.com/ai/understand-breeze)
- [HubSpot: AI product page](https://www.hubspot.com/products/artificial-intelligence)
