Set up the HubSpot integration
oHallo is an autonomous agent platform for customer operations. Its agents answer inbound customer conversations across chat, email, SMS, WhatsApp and voice, work from your own knowledge base and policies, and carry out the work a conversation implies, with a human in the loop wherever you decide judgement matters.
This integration lets those agents work with the records in your HubSpot account while a conversation is happening: finding the contact who is writing, reading the deal or ticket the question is about, and writing back what changed, without anyone leaving the conversation to look it up.
Nothing is copied into oHallo to make this work. Each request is made live against HubSpot at the moment an agent needs it, through HubSpot’s own hosted MCP server, using the access a HubSpot administrator in your account granted. There is no scheduled sync, no bulk export and no background crawl of your account.
What the integration powers
Section titled “What the integration powers”Once connected, the HubSpot tools appear alongside your other capabilities in oHallo and can be assigned to any specialist agent you have built. Typical use:
- Answering with context. An agent identifies the customer writing in and reads their HubSpot record before it replies, so the answer reflects who they are and what they have bought.
- Working the conversation’s aftermath. An agent logs what happened, updates a property, or creates the follow-up record a resolved conversation implies.
- Keeping humans in front of the decisions that matter. Every HubSpot tool call passes through oHallo’s guardrails first, so you can require human approval, block a tool outright, or mask fields out of a result before an agent ever sees them.
What the agents can actually do is bounded three times over: by the tools HubSpot’s MCP server exposes, by the permissions granted during installation, and by the HubSpot permissions of the user who connected. Those bounds are described under Limitations and known behaviours.
Before you connect
Section titled “Before you connect”In HubSpot
Section titled “In HubSpot”| Requirement | Who | Applies |
|---|---|---|
| A HubSpot account admin must complete this connection themselves, first. Only after an admin has connected can other users in the same account connect. | A HubSpot account administrator | Always |
| The connecting user needs the HubSpot App Marketplace Access permission, plus permissions matching every scope they approve. Holding one without the other still fails. | The person connecting | Always |
| In accounts opted into HubSpot’s app install governance, the app must additionally be approved there. An unapproved app is refused at install time. | The person connecting | Only some accounts |
The admin-first sequencing is the most common way a first connection fails, and it fails silently from the connecting user’s point of view: they are simply refused at HubSpot. If you are not an administrator of the HubSpot account, ask one to run through this guide once before you try it yourself.
The App Marketplace Access requirement applies to the first install. Afterwards the same user, or other users in the account, can connect without it, as long as the installation does not request any new scopes.
In oHallo
Section titled “In oHallo”- An oHallo account with a workspace to connect into.
- The owner or admin role in oHallo. Other roles can see the MCP hub but cannot add, reconnect or delete a connection.
Install the integration
Section titled “Install the integration”Everything starts in oHallo. There is nothing to install from inside HubSpot, and in the normal case nothing to build there either.
1. Open the MCP hub
Section titled “1. Open the MCP hub”Sign in to oHallo at app.ohallo.eu and open MCP hub from the sidebar, under
Capabilities. The Installed tab lists your existing connections; Browse is the
catalogue of connections you can add.
2. Choose HubSpot
Section titled “2. Choose HubSpot”Select Add MCP server in the top right, then choose the HubSpot card from the catalogue. You can filter the catalogue by category; HubSpot is under CRM.
3. Review the prerequisites and choose a scope
Section titled “3. Review the prerequisites and choose a scope”The connection form opens. It restates the HubSpot-side prerequisites above under Before you connect, labelled with who has to do each one.
There are no credentials to collect first. oHallo never asks for a HubSpot API key or a private app token, and you do not have to build an app in HubSpot: the connection goes through oHallo’s own HubSpot app, and the only fields on the form are optional.
The decision that matters on this screen is Scope, which controls how widely the connection is available inside oHallo:
| Scope | Who can use it | Choose when |
|---|---|---|
| Organisation | All brands and workspaces | One HubSpot account serves your whole organisation. |
| Brand | All workspaces in one brand | Each brand runs its own HubSpot account. |
| Workspace | One workspace only | A single team or region uses this HubSpot account. |
The form also offers a Client ID and Client secret, both marked only if using your own app. Leave them blank — that is the normal path, and it connects through oHallo’s HubSpot app. Fill them in only if your organisation has registered its own HubSpot app and wants the grant to sit under that app instead; in that case both are required, since a client ID without its secret is refused before anything is created.
Select Continue to HubSpot. oHallo starts an OAuth 2.1 authorisation with PKCE against HubSpot’s MCP server and hands you over.
4. Choose the HubSpot account
Section titled “4. Choose the HubSpot account”HubSpot takes over and asks which of your HubSpot accounts you are connecting. Pick the one whose records the agents should work with. If you belong to several accounts, this is the only place the choice is made — oHallo never sees your HubSpot credentials and cannot make it for you.
5. Approve the permissions
Section titled “5. Approve the permissions”HubSpot then shows what oHallo would be able to do and asks you to approve it. Read this screen carefully: it is where you decide the integration’s ceiling.
oHallo requests no scopes of its own. It sends no scope parameter at all. HubSpot derives
what is on offer from the tools its MCP server currently exposes and from what you tick here,
and the grant that comes back is exactly what you approved — nothing wider. Approve the reads
and writes your agents genuinely need and leave the rest; you can widen it later by
reconnecting.
6. Confirm the unverified-app step
Section titled “6. Confirm the unverified-app step”HubSpot shows an additional confirmation step for third-party apps it has not verified, and asks you to confirm explicitly, in writing, that you accept the risk before it continues. Expect this step while the oHallo listing is under review.
7. Return to oHallo
Section titled “7. Return to oHallo”HubSpot sends you back to oHallo, which exchanges the authorisation, stores the credential, resolves the regional endpoint for your account, and immediately probes the connection for tools. While that probe runs the connection reads Connected — probing the endpoint for tools now; the tool list fills in a moment later.
The connection is now on the Installed tab. Open it to see the endpoint in use, the tools that were discovered, and everything described in Configure the connection.
If something failed on the way back, oHallo says which side failed and whether anything was left behind — including the case where HubSpot did grant access but the connection could not be created, where you are told to revoke the grant in HubSpot if you do not intend to retry.
What gets connected
Section titled “What gets connected”The connection exposes HubSpot’s MCP tools to oHallo: reading and searching CRM records, reading account and user details, and creating or updating records where you approved write access. The exact list depends on what you approved and on which tools HubSpot’s MCP server exposes at the time you install. A portal connecting with broad permissions returned 22 tools when oHallo last verified this end to end, in August 2026.
The connection page lists every discovered tool with the description HubSpot supplies. Treat that list, not this page, as the authoritative account of what your connection can do.
Where the data goes
Section titled “Where the data goes”Authorisation runs through HubSpot’s global host, mcp.hubspot.com. That traffic carries
credentials and consent, not CRM records.
Tool calls do not. HubSpot pins each account to a single region, so after authorisation oHallo resolves your account’s HubSpot data hosting location and sends every subsequent tool call to the regional host that matches it:
| Your HubSpot region | Tool calls go to |
|---|---|
| EU (Frankfurt) | mcp-eu1.hubspot.com |
| US East (Virginia) | mcp-na1.hubspot.com |
| US West (Oregon) | mcp-na2.hubspot.com |
| Canada (Montreal) | mcp-na3.hubspot.com |
| Australia (Sydney) | mcp-ap1.hubspot.com |
An EU account’s tool calls therefore stay on HubSpot’s EU host. The resolved endpoint is on the connection page, so you can confirm it rather than take it on trust. If the region cannot be resolved, oHallo falls back to the global host and records that as an explicit exception.
What moves, and in which direction
Section titled “What moves, and in which direction”| Direction | What moves | When |
|---|---|---|
| oHallo to HubSpot | One tool call: the tool’s name and its arguments, such as the email address to search for or the fields of a note to create | Only when an agent calls the tool during a conversation, or when you test the connection |
| HubSpot to oHallo | That call’s result: the records or the confirmation HubSpot returns | In response to each call |
Records in HubSpot are created or changed only when an agent calls a write tool — only if you approved write permissions, and only if you assigned that tool to an agent. oHallo does not import contact lists or email addresses into HubSpot, and does not enrich your HubSpot records from third-party sources.
oHallo keeps no synchronised copy or search index of your HubSpot account. Each call’s arguments and result are recorded in the conversation’s audit trail, so the exchange can be reviewed afterwards; that record follows oHallo’s published retention, described under What happens to your data.
Credentials
Section titled “Credentials”The credential HubSpot issued is held in oHallo’s secrets store, never in the application database, and is refreshed automatically before it expires. You do not have to renew anything on a schedule. If HubSpot ever invalidates the credential, the connection shows an error and offers Reconnect, which replaces the credential and keeps the connection’s tools, guardrails and agent assignments intact.
Configure the connection
Section titled “Configure the connection”A newly installed connection is inert until you configure it. Nothing reaches an agent by default.
1. Classify each tool’s risk
Section titled “1. Classify each tool’s risk”Every tool must carry a risk classification before it can be called. An unclassified tool is denied on every call — an unknown capability is treated as maximum risk, not waved through.
Set each tool’s Risk on the connection page. The classification determines the assurance floor a caller must clear before the tool will run:
| Classification | Use for | Required assurance |
|---|---|---|
read | Public or non-personal data | Anonymous |
read_pii | Anything returning personal data | Identified |
write | State-changing actions | Identified |
write_pii | State-changing actions that also touch personal data | Identified |
destructive | Irreversible or financially material actions | High assurance |
You can raise a tool above its floor, never below it.
2. Assign tools to agents
Section titled “2. Assign tools to agents”Assign each tool to the specialist agent that should be able to call it. A tool assigned to no agent is unreachable: it is inert, not available by default. The connection page shows how many of the discovered tools are assigned and warns while any are not.
Give each agent the smallest set of tools its job needs. An agent that answers order questions does not need the tools that change deal stages.
3. Add guardrails
Section titled “3. Add guardrails”Guardrails are deterministic rules evaluated on every tool call, before it executes. Use them to put the decisions you care about in front of a person:
- Deny blocks a tool outright, with or without a condition.
- Approval gate pauses the call, raises an attention item in oHallo, and waits for a human to approve or reject before the agent continues.
- Mask lets the call run but removes named fields from the result before the agent sees them.
- Escalate lets the call run and flags it for review afterwards.
Any tool you classified as destructive already requires approval by default when no other
rule matches it. See Guardrails for conditions and the full evaluation
order.
4. Write agent instructions
Section titled “4. Write agent instructions”The connection page has an Agent instructions field. Use it to tell agents when to reach for HubSpot and what your conventions are — which property holds the customer’s plan, what a note should contain, when to create a ticket rather than reply. Instructions are read by every agent using the connection.
Using the integration
Section titled “Using the integration”Day to day there is nothing to operate. A customer writes in; the agent handling the conversation decides whether it needs HubSpot; if it does, it calls a tool it has been assigned, oHallo evaluates the assurance gate and your guardrails, the call goes to your account’s regional HubSpot host, and the result comes back into the conversation.
- Automatic use is the normal path: the agent decides, mid-conversation, that it needs a record and fetches it. Nobody is prompted.
- Human-in-the-loop use happens when a guardrail gates a call. The conversation pauses, an attention item appears in oHallo with the tool name, the arguments and the rule that fired, and a person approves or rejects it. Approvals expire after 24 hours and an expired request is treated as a rejection.
- Manual use is available on the connection page: Test re-probes the endpoint and refreshes the tool list, which is also how you check the connection after changing anything in HubSpot.
Every call is written to the conversation’s audit trail with its arguments, its result and the guardrail decision that allowed it.
Limitations and known behaviours
Section titled “Limitations and known behaviours”Sensitive Data blocks activities and conversations, through the MCP server only. If your HubSpot account has HubSpot’s Sensitive Data feature turned on, activity objects — calls, emails, meetings, notes and tasks — and conversation data are blocked from access through HubSpot’s MCP server. This restriction is specific to the MCP server and does not apply to HubSpot’s standard CRM APIs. The connection will still install and report itself healthy; the capability simply will not be there. If your account has Sensitive Data enabled, confirm what the connection can actually reach before you rely on it.
Access to the HubSpot conversations inbox follows HubSpot’s own restrictions. If inbox access is restricted to specific users or teams in HubSpot, only those users can query those conversations through the MCP server.
The connecting user’s HubSpot permissions are a continuous ceiling. The connection acts as the HubSpot user who created it, and every action respects that user’s HubSpot permissions at the time of the call. This is not a one-time grant ceiling: if that user’s role is narrowed later in HubSpot, what oHallo can do narrows with it, immediately and silently. Connect with a user whose permissions match the job you intend the agents to do, and expect to revisit the connection if that user’s role changes or they leave.
New HubSpot tools need a reconnect. HubSpot determines available scopes from the tools its MCP server exposes at the time you install. When HubSpot adds tools, the scopes available may change, and accounts that already installed have to reconnect to grant the new ones. Existing tools keep working in the meantime. Use Reconnect on the connection page; your tools, guardrails and agent assignments are kept.
Widening permissions requires the same reconnect. If you approved a narrow set at install and later need more, reconnect and approve the wider set. There is no way to widen a grant from inside oHallo.
Reconnecting must use the same HubSpot account. A reconnect signed in against a different HubSpot account is refused and nothing is changed. To connect a second HubSpot account, install a second connection into a different workspace instead.
Disconnect the integration in oHallo
Section titled “Disconnect the integration in oHallo”Open the connection from the MCP hub and select Delete connection.
The moment you confirm:
- The connection is removed from every agent that used it, and no agent can call any of its tools again. There is no grace period and nothing to switch off separately.
- The cached access token is dropped.
- The stored credential, both the access token and the refresh token, is deleted from oHallo’s secrets store.
The connection’s own record is retained in oHallo for audit history; the credential is not.
Deleting the connection in oHallo does not revoke anything in HubSpot. The grant you approved is still live in your HubSpot account until you also uninstall the app there. If you are disconnecting for security reasons, do both.
Uninstall the app in HubSpot
Section titled “Uninstall the app in HubSpot”In HubSpot, open your account settings, go to the connected apps list under Integrations, find the oHallo app and uninstall it.
Three things are worth knowing before you do:
- Revocation is account-wide. Revoking approval for the app uninstalls it for every user in that HubSpot account who had previously installed it, not only for you.
- It is not instant. HubSpot states that uninstall actions can take up to 30 minutes to take effect.
- Per-user uninstall is a different action. HubSpot supports removing an individual user’s install separately from revoking the app for the account, so an account can end up partly connected — some users’ grants gone, others still live.
After uninstalling in HubSpot, delete the corresponding connection in oHallo as well, if you have not already. Left in place it will simply start failing, because the credential behind it no longer authorises anything.
What happens to your data
Section titled “What happens to your data”In your HubSpot account. Disconnecting in oHallo and uninstalling in HubSpot delete nothing from HubSpot. Records that an agent created or updated while the integration was connected stay exactly as they are; oHallo does not roll anything back. Uninstalling only ends oHallo’s access.
In oHallo. The HubSpot credential is deleted immediately, as described above, and no further data can be read from or written to your HubSpot account. What remains is the record of what already happened: conversations, and the audit trail of the tool calls made during them, including the arguments sent and the results returned.
That history is not deleted by disconnecting — deleting a connection is not a request to erase the conversations that used it. It follows oHallo’s published retention: conversation data and messages are kept for the duration of the subscription and deleted within 90 days of termination, and backups containing deleted data are overwritten within their normal rotation cycle, at most 30 days. Contact and account records and attachments follow the same schedule. The full schedule is in the oHallo privacy policy.
If you need that history removed sooner than the retention schedule provides, or need to exercise a data subject’s right to erasure, contact oHallo directly.
If something goes wrong
Section titled “If something goes wrong”| What you see | What it means |
|---|---|
| HubSpot refuses the install | Most often the admin-first prerequisite, or the connecting user lacks App Marketplace Access or the permissions matching a scope they approved. Have a HubSpot account admin connect once, then retry. |
| The connection installs but no tools appear | The probe may still be running; the page says so while it is. If the list stays empty, use Test on the connection page to re-probe. |
| Tools are listed but agents never call them | Check that each tool has a risk classification and is assigned to an agent. Unclassified tools are denied, and unassigned tools reach no agent. |
| Calls that used to work now fail | Usually the connecting user’s HubSpot permissions changed, or the credential was invalidated. Open the connection; if a repair is needed it offers Reconnect. |
| Activity and conversation tools return nothing | Check whether HubSpot’s Sensitive Data feature is enabled on the account. See Limitations and known behaviours. |
Support
Section titled “Support”- Help centre: help.ohallo.ai
- Contact oHallo: ohallo.ai/contact
- Privacy policy: ohallo.ai/privacy
- Terms of service: ohallo.ai/terms