Everyone wants to rank the API, MCP and the CLI. Wrong question. Pick by who is doing the work, and by how much damage a mistake can do.
The difference between the API, the MCP server and the Agent CLI is new, and it is usually explained as a ranking. We think that is the wrong frame. Our portal audits read client portals through the API, and in August 2026 two of them taught us exactly what each layer does and does not tell you. The difference matters more than the acronyms suggest.
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 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.
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.
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.
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.
| If you are | Use | Because |
|---|---|---|
| Building a custom integration that runs unattended | API | Stable, date-versioned, no agent in the loop (each version is supported for 18 months, so plan upgrades) |
| Powering an in-app AI experience where the agent must discover what is possible | MCP | Discovery at runtime is the whole point |
| Running an agent in a terminal on bulk or repetitive CRM work | Agent CLI (public beta) | Fewer tokens, fewer misfires, dry runs where available |
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.
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.
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.
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.
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.