HubSpot's MCP server reached general availability on 13 April 2026, it reads and writes live CRM data, and it works on every HubSpot plan at no extra cost. Connecting it takes about ten minutes. Deciding what it is not allowed to touch takes a week, and that is the only part worth reading about.

Every walkthrough you will find covers the ten minutes. This one covers the week.

What is the HubSpot MCP server?

Model Context Protocol is a standard way for an AI model to ask an external system for something and get a structured answer back. Before it, every integration between a model and a tool was bespoke. With it, the tool exposes a server, and any compatible client can talk to it without anyone writing glue code.

HubSpot runs an official one at mcp.hubspot.com. It began as a public beta in September 2025 and went generally available on 13 April 2026, with expanded read access and CRM write support. It works with any client supporting OAuth 2.1 with PKCE, which in practice means Claude, Cursor, VS Code, ChatGPT's developer mode, and anything you build yourself.

The official documentation is here, the integration guide for the remote server is here, and the protocol specification itself is at modelcontextprotocol.io.

What that means in a sentence: an assistant can now read and change your CRM in conversation, on a plan you already pay for.

What can it read and write?

Read access covers the CRM objects you would expect: contacts, companies, deals, tickets, and the properties, associations and engagement history hanging off them. Write access covers creating and updating those records.

That is the whole story, and it is also why this is not a small feature.

"Update deals" is one capability from the model's side and about fourteen different risk conversations from yours. An assistant that can update a deal can also close one, change its amount, reassign its owner, or quietly rewrite a property that three dashboards and a board report depend on.

None of that is a flaw in the protocol. It is exactly what you asked for. It just means the interesting design work is subtraction rather than addition.

How do you stop an agent writing to the wrong records?

Four controls, in the order we apply them. The first two are free and most people skip them.

1. Scope the connection, not the prompt

The temptation is to tell the model what not to do. Do not rely on that. Instructions are guidance. Permissions are enforcement. The difference matters the first time a model interprets your instruction creatively at 2am.

Grant the narrowest set of scopes that lets the job happen. Where read will do, grant read. A surprising number of jobs people describe as "the agent updates the CRM" turn out, on inspection, to be "the agent tells a human what to update".

2. Separate the identity

Do not let the agent borrow a human's session. Give it its own connection with its own permissions, so what it did is distinguishable from what a person did in the audit history.

When something goes wrong, the first question is always "who changed this". If the answer is the name of whoever happened to authorise the integration, you have lost your audit trail and put a colleague in an awkward position.

3. Put the destructive verbs behind a human

Reading is cheap to get wrong and expensive to forbid. Writing is the reverse.

Our default is that an agent proposes a write and a person approves it, until the eval set says the agent is better at that specific decision than the person is. Sometimes it gets there. Often it does not, and the proposal step turns out to be the actual product, because what the team wanted was a good first draft rather than autonomy.

4. Constrain by object, not just by action

"Can update deals" is too coarse to reason about. "Can update the next-step property on deals it has already been handed, and nothing else" is a rule you can hold in your head, explain to a security reviewer, and test.

The general shape: bound the verb, bound the object, bound the field, and bound the set of records it can reach.

The Australian bit nobody puts in the tutorial

Every MCP walkthrough is about capability. Here is the part that decides whether it survives a risk review in an Australian business.

An agent with CRM access is a new breach surface

Under APP 11 you must take reasonable steps to protect the personal information you hold. If something goes wrong, the Notifiable Data Breaches scheme gives you 30 days to assess a suspected eligible breach and, if it qualifies, notify the OAIC and the affected individuals.

A connection that can read every contact record in your portal is worth thinking about in those terms before it is worth demoing to the leadership team.

The records are Australian, so the failure modes are too

Test with real shapes, not sample data:

  • ABNs and ACNs as the company identifier, because names will not deduplicate reliably.
  • Mobile numbers in two formats, arriving as both +61 4XX XXX XXX and 04XX XXX XXX. An agent normalising to a North American format is not hypothetical.
  • State and territory as free text: QLD, Qld, Queensland, and the occasional typo, all meaning one thing.
  • Four digit postcodes where a spreadsheet has eaten the leading zero, so 0800 arrives as 800.

A US-authored tutorial will never mention any of this, and every one of them produces confident, fluent, wrong output.

Consent, if the agent can send anything

If your agent can trigger a marketing send, it now sits inside the Spam Act 2003, where the burden of proving consent falls on you and you cannot outsource the obligation. Express and inferred consent are distinct in Australia, and an agent does not know the difference unless your data does.

And the December obligation

From 10 December 2026, transparency obligations for automated decision making land in the Australian Privacy Principles. If your agent makes decisions about people that significantly affect their rights or interests, that belongs in your privacy policy. Worth knowing before you build, not after.

The ASD's guidance on deploying AI systems securely is the right companion reading, and it is written for organisations of exactly this size.

Wondering whether your portal is ready for this?

Most of what goes wrong when an agent reads a CRM is not the model. It is the data underneath. The audit tells you which one you are dealing with.

Get your AI readiness score

Does it need a paid plan?

No. It works on every HubSpot plan at no extra cost, which is the detail that changes who can experiment.

You do not need a procurement conversation to try this. That is the good news, and from a governance point of view it is also something your security team should probably know is true, because it means somebody in your business may already have connected it.

Be clear about what is and is not free: the connection costs nothing, the model usage does not. If you are working out what the running cost looks like at 150 people, we did that arithmetic in Breeze credits or your own API key.

When to use this instead of a workflow

Three columns now, not two. This is the table we actually reason with.

 

  Native workflow Breeze agent MCP and a custom agent
Use when The rule is deterministic and you can write it down The job is one HubSpot built, and the default behaviour fits The job needs judgement, or data outside HubSpot, or behaviour you must be able to measure
Time to live Hours Hours Weeks
Can you evaluate it Not needed No Yes, and you must
Reaches other systems Limited No Yes
Who owns the behaviour You HubSpot You

The honest test: if you cannot describe what a good answer looks like, you cannot evaluate the agent, and you should not give it write access.

We wrote the decision between the first two columns in HubSpot AI agent or simple workflow, and the running cost of the native agents in what HubSpot's AI agents actually cost to run. This piece is the third column, and the fuller argument for when you need it is in Agent Hub and Agent Builder.

What we would do first

  1. Connect it read-only to a sandbox or a low-stakes portal. Ten minutes, no approvals needed.
  2. Ask it the questions your team actually asks the CRM. "Which deals have gone quiet." "What did we agree with this client in March." "Which accounts have no next step."
  3. Write down the three writes you would eventually want, and what a wrong version of each would cost you.
  4. Only then talk about granting write access, and grant it to the narrowest of the three.

Step two is the one that surprises people, and it is the reason to do this even if you never grant a write. An assistant reading your CRM out loud is an unusually blunt mirror. Most of what it gets wrong is not the model. It is that two records disagree, or the association is missing, or the field everyone relies on has been empty since March.

Which is a different article: how to score your HubSpot support tickets for AI readiness is the narrow version, and the permissions side is how to deploy HubSpot AI agents without breaking your data.

Frequently asked

Is the HubSpot MCP server safe to connect to a production portal?
Read-only, with its own connection and scoped permissions, yes, and that is where we would start. Write access to production is a decision that deserves the four controls above rather than a Tuesday afternoon.

What is the difference between MCP, the API and the CLI?
The API is how software talks to HubSpot. The CLI is how a developer works on HubSpot assets from their own machine. MCP is how a model asks HubSpot for something in the middle of a conversation. They are complementary, and a serious build often uses all three.

Can I limit it to specific records rather than specific objects?
That is the constraint you want and it is the one worth designing for deliberately, because object-level permissions alone are usually coarser than your risk appetite.

Does using MCP send our CRM data to a model vendor?
It sends whatever the model asks for, which is why scoping matters. Where that request is processed and what is retained depends on how you access the model, which we covered in where your data actually goes when Claude reads your CRM.

Do we still need Breeze if we have this?
Usually yes. Breeze does the common jobs immediately with no build. This is for the jobs it cannot do. Exhaust the native tooling first.

Where to go from here

We are the only Australian firm holding both a HubSpot Diamond partnership and Anthropic certified which mostly means we have made these mistakes on our own portal before making them on anyone else's.

 

Want to see what we would connect, and what we would refuse to?

We will look at your portal, tell you which jobs are worth an agent.

Get your AI readiness score

Or talk to us about a build.

 

A question to leave you with. If an agent could change one field in your CRM tonight and nobody noticed until Monday, which field would hurt most? That is the one to put behind a human.

Sources