API, MCP and CLI: HubSpot's three AI integration layers, and when to use each

Three layers, one platform

HubSpot gives AI three ways into the same CRM data: the REST API for software, MCP for agents that discover what is possible at runtime, and the Agent CLI for agents working in a terminal.

The API: built for applications

The REST API is the layer HubSpot has offered for years. You write code, the code calls an endpoint, the endpoint returns data or makes a change. It is explicit, well documented, and it powers most integrations you have never thought about: your form software talking to HubSpot, your billing tool syncing invoices, a custom app pulling deal data into a dashboard.

The API is for developers building durable software. It is not "for AI" in any special sense. An agent can call it, but it has to be told exactly what to call and how, the same way a human developer does. There is no discovery built in, and that is a feature, not a gap. Stability is the point.

Explicit also means it tells you exactly what it says and nothing more. In both portals we audited in August 2026, the users endpoint returned deactivated users with no status field, and our first pass overstated super admins: close to double the real number in one portal, four times in the other. We caught it by cross-checking the Users object and the UI. The API did what it said; it did not say what we assumed.

Stable does not mean permanent. Since 2026.03 HubSpot versions its API by date, twice a year, each version supported for 18 months. The older numbered APIs now have a calendar: v4 support ends on 2027-03-30, and v1 to v3 endpoints and legacy private apps become unsupported in September 2027. Creating new legacy private apps is being switched off this autumn, with service keys (public beta) named as the replacement. An integration built today should be built on a dated version.

MCP: built for agents that figure things out live

Model Context Protocol is different in one specific way. It is discoverable. An agent connected to a HubSpot MCP server does not need a list of valid endpoints handed to it in advance. It can ask what is available and get a machine-readable answer back. That is the whole purpose of the protocol: an open standard for connecting models to external tools and data without hand-coding every integration path (HubSpot MCP server docs).

In practice, MCP is what powers in-app AI connectors, where you ask a question inside a tool you are already using and it reaches into HubSpot in real time to answer. Worth knowing: HubSpot ships two separate MCP servers under one name, a remote CRM server for agent-to-data access and a local developer server for building apps and CMS assets. They solve different problems, and conflating them is the most common source of confusion when people first go looking. As of the Fall 2026 release there is a third direction too: an app can add an MCP server component that exposes its own tools inside HubSpot's agents, so MCP now runs into HubSpot as well as out of it.

CLI: built for agents that already live in a terminal

This is the layer we think is most underrated, and it is the one we lean on hardest. Coding agents, the kind operating inside a terminal, are fluent in shell commands, because shell is the pattern they have seen most. In our experience they produce a correct command more reliably than a correct tool call against a schema they have just discovered. A CLI is also lighter on context window than a full tool schema and noticeably faster for bulk or repetitive operations.

HubSpot's Agent CLI is built for exactly this: an agent in your terminal that can read and write CRM data, run bulk operations, and do the unglamorous repetitive work that RevOps, sales ops and marketing ops teams have always had too much of. It moved to public beta in HubSpot's Fall 2026 release, and its help page still carries the beta label. HubSpot Diamond Partner Niv Lamerovich put the framing well in a widely shared breakdown: a lot of ops work "is not strategic. It is repetitive." That is precisely the category CLI-driven agents should take over, from Monday morning deal-risk summaries to daily CRM cleanup queues to pre-QBR account digests.

The thesis: it is not about which layer is best

No layer is best. The right one depends on who is doing the work and where they are already operating. The instinct is to rank these and default to the winner, and that is the wrong frame.

We run all three, and not hypothetically. Cross-service work, where HubSpot has to talk to Slack or Google Drive in the same flow, goes through a connector layer. Bulk CRM operations go through the Agent CLI, which has purpose-built dry-run checks. Quick live reads inside an active session go through MCP, where discoverability matters more than raw speed.

Running more than one also catches what a single layer misses. At the time of our August audit, one portal had three live workflows built in HubSpot's newer agentic workflow builder. One read tool showed them as empty, and the automation API could not read that flow type at all. They were working. An audit that trusted one layer would have reported three broken workflows that were doing their job.

The stance we actually operate by

We route by blast radius, not by layer: what an operation can break decides the safeguards, and the tool follows from that. Choosing the layer is not the safety decision.

• Routine. One record, reversible, our own portal. Either path, no dry run needed.
• Consequential. Bulk operations, field changes across records, and anything at all on a client portal. Dry run first, every time, and confirm which portal you are pointed at before the write.
• Irreversible. Deletes, merges, schema changes, publishing a workflow. Dry run plus an explicit instruction from a human for that specific action.

Two things fall out of that. First, an execute tool that cannot preview a change is only ever safe for the first tier, no matter how convenient it is. Second, the safety mechanism is the tier, not the binary. Both of our main paths have a dry-run flag, so picking the "safe tool" is not a control. Deciding what the operation can break is.

The competitive angle most people miss

HubSpot built these three layers to meet agents where they already operate, in your terminal, your editor, your existing connectors, rather than requiring a separate proprietary agent framework to get AI value out of your CRM. That is a real point of differentiation against platforms that make you step inside their ecosystem first.

For an ecosystem that has spent two decades explaining HubSpot in terms of hubs and tiers, this is a genuinely new question buyers are starting to ask. Not "what does HubSpot cost," but "how do I let an agent work inside it safely." Our guess is that few partners have had to build an answer yet.

Where to start if this is new

Do not stand up all three at once. Start with the layer that matches the work in front of you. A one-off integration project points to the API. An AI feature inside a tool your team already uses points to MCP. A backlog of repetitive CRM cleanup points to the CLI. The mistake is not picking the wrong one, it is assuming there is only one option.

Sometimes the right answer is none of them. Skip the CLI if nobody on your team lives in a terminal or you have no repetitive backlog; it is a public beta, so do not hang unattended jobs on it yet. Skip a custom MCP build if a built-in connector already answers your question. And if your data is the problem, no layer helps.

And before any of it: the layers are only as good as the data underneath them. Great architecture gets leverage from AI. Messy architecture just produces faster chaos. If you are not sure which category yours is in, that is a fair question to bring into a HubSpot Portal Audit.