Back to Blog
HubSpotMCPRevOps

HubSpot MCP Server: Setup, Limits and a Safe RevOps Rollout

Abhishek Singla Nov 16, 2026 17 min read
The short answer

Authorise a narrow user

Connect HubSpot's remote MCP server from a dedicated user with a narrow permission set, over OAuth with PKCE (Proof Key for Code Exchange). Every call runs as that user, so start with questions and treat every write as a change that user is making by hand. The documented tools do not delete records, the query tool does not join records or walk associations, and Sensitive Data changes which emails, notes and conversations the connector can see.

HubSpot's remote MCP server (Model Context Protocol) lets an assistant read and update the CRM over a connection HubSpot hosts. In our CRM and RevOps work, the permission set is the decision and the connector is the last step. How Claude fits the rest of a go-to-market stack is the Claude for GTM guide. This page is the server itself: what it exposes, where it stops, and the order we recommend so the assistant cannot see more than the person who authorised it.

Cover for the HubSpot MCP server guide. Connect the server as a narrow HubSpot user, then review every write.

What the HubSpot MCP server is

The remote server lives at https://mcp.hubspot.com. HubSpot's developer page describes it as a bridge between an MCP client and one account's CRM data, with each request authenticated as a HubSpot user. It left beta and became generally available on 13 April 2026, for all HubSpot accounts. That release added write access, activity history, marketing content and organisational context, and it requires OAuth 2.1 with PKCE on every connection (HubSpot changelog, 13 April 2026, checked 16 Nov 2026). The changelog was corrected on 15 April 2026. Where it disagrees with the current developer page, follow the current page.

HubSpot ships a second MCP server, and the two get mixed up in setup guides. The developer MCP server installs on your machine with hs mcp setup, needs the HubSpot CLI at version 8.2.0 or higher, and appears in the client as HubSpotDev. It is for building apps and CMS assets locally (developer MCP setup). A guide that starts with hs mcp setup is that server. The RevOps server is the remote one, and HubSpot's changelog says the same split.

Any MCP client that can finish OAuth with PKCE can connect to the remote URL. HubSpot also publishes ready-made connectors for Claude and for ChatGPT, so a team can skip hosting its own OAuth client. A handful of content tools, including website pages, blog posts and the preview card, are offered only to the AI clients named on the developer page. Under the hood the server uses the CRM search API, which HubSpot says does not include vector search (remote MCP server docs). A prompt that asks for "records like this one" will not get a semantic match.

Connect it in five steps

The developer page, checked 16 Nov 2026, calls the screen MCP Connectors. The April changelog still says Development, then MCP Auth Apps. Use the label in the account you have open.

  1. In HubSpot, open Development, then MCP Connectors, then Create MCP connector. Enter a name, an optional description, and the redirect URL the client will send the user back to. If you add more than one redirect URL, HubSpot uses the first as the default. To test with the MCP Inspector, include http://localhost:6274/oauth/callback/debug (remote MCP server docs).

  2. Open the connector's details page and copy the client ID and the client secret. Both are credentials. Keep them out of a repository and out of a prompt someone might paste into chat.

  3. Point the client at https://mcp.hubspot.com. PKCE is required. HubSpot's Inspector steps use the Streamable HTTP transport, that URL, and the client ID and secret. The page does not publish a JSON config, so this guide does not invent one. If your client builds the OAuth request itself, HubSpot's troubleshooting note is specific: a code verifier of 43 to 128 characters, an S256 code challenge on the authorisation request, and the same verifier when you exchange the code. A client that skips PKCE fails the token step.

  4. Sign in as the dedicated user, pick the HubSpot account, and grant only what that user should have. You do not design the connector's scopes on a separate screen. HubSpot builds them from the tools available on the day of install, plus the permissions the user accepts. When HubSpot adds tools later, an existing install has to be reinstalled before the new scopes are granted (remote MCP server docs).

  5. Run get_user_details before any business question. HubSpot says the response returns the authenticated user, account details, per-object read and write access, and the default brand. It is also the check for which tools this account and this user actually have. If the name in the response is a super admin, disconnect and authorise the narrow user.

Claude's connector skips the Development screen. A Super Admin, or a user with App Marketplace access, can connect it without a prior approval. Everyone else needs a Super Admin to approve the app and choose its data permissions first. In Claude the path is Settings, Connectors, then HubSpot (Claude connector article, updated 12 Nov 2026). In ChatGPT the path is Settings, Apps, then HubSpot (ChatGPT connector article). Both still authorise as a HubSpot user. One Claude account connects to one HubSpot account at a time. Switching portals means disconnecting and connecting again.

Access tokens expire. After a quiet period the client should refresh with the refresh token from the first grant. If that token is dead too, run the full OAuth flow again. A redirect URL in the client that does not match the connector produces the same kind of failure (remote MCP server docs).

What it can read and write

Which tools answer depends on the subscription, the user's permissions and the account settings. get_user_details is the check for one portal. The public list below is from the remote MCP server docs and the Claude connector article, both read 16 Nov 2026. The April changelog's object list is shorter. The current pages include custom objects, and they are the ones to follow.

AreaReadWriteCatch
CRM recordsContacts, companies, deals, tickets, leads, users, custom objectsCreate and update, including custom object recordsNo delete. Conditional property rules and pipeline stage checks still run. Association label checks do not
Revenue objectsCarts, invoices, orders, line items, products, quotes, subscriptions. Read is marked beta on the developer pageLine items and products. Quotes are betaClaude's table shows invoices, orders, carts and subscriptions as read only. Quote writes need Revenue Hub Professional or Enterprise
ActivitiesCalls, emails, meetings, notes, tasksCreate and update the same fiveSensitive Data changes who can see them. No delete
ConversationsInbox and help desk messages and threadsNot in the write listBlocked through the MCP server when Sensitive Data is on
ContentBlog posts, landing pages, site pages, campaigns, marketing events, email analyticsCreate and edit pages, posts, campaigns and email drafts. Publishing asks for confirmationWebsite pages, blog posts and the preview card are limited to the AI clients named on the developer page
Query toolsSearch, fetch by ID, and a SQL-style queryThe query tool readsNo joins, subqueries, association walks, column aliases or currency conversion. No vector search
Properties and pipelinesProperty definitions and pipelinesCreate properties. Create pipelines, except on free tools, which can edit the default pipelineNew scopes need a reinstall
AEOBrand metrics and tracked promptsCreate prompts and start content actions, with confirmationMarketing Hub Professional or Enterprise

search_crm_objects returns at most 200 records a page, with up to five filter groups and six filters in a group. Filters inside a group are combined with AND, and groups are combined with OR. get_crm_objects accepts at most 100 IDs in one request. search_owners stops at 100 results. search_properties takes at most five keywords (remote MCP server docs).

manage_crm_objects is the write. Before it runs, the tool shows a summary of the proposed changes and waits for an explicit confirmation. The same confirmation pattern is documented for segments, campaigns, landing pages, website pages and blog posts. On the Claude and ChatGPT connectors, a bulk create or update is capped at 10 records in one request (Claude connector article, ChatGPT connector article). The developer tool list does not state that cap outside those two connectors. Treat 10 as the Claude and ChatGPT limit, and test a small write on any other connector before assuming the same ceiling.

Custom object records are on the read list and the write list. Claude's table gives them a tick for read, create and update, and a dash for delete. Whether the portal should have the object in the first place is a data-model decision, covered in the custom objects guide. The MCP server can address records of an object that already exists. The query tool still cannot walk from that record to its associations.

The limits that surprise teams

There is no delete. Claude's object tables leave the Delete column empty on every row, and the article says the connector supports view, create and update. Asking it to clear a phone number is a documented refusal. Someone deletes the record, or the value, inside HubSpot (Claude connector article).

The query tool cannot join the story together. query_crm_data filters, aggregates and sorts. HubSpot states that it does not support joins, column aliases, subqueries, association traversal or currency conversion. "Deals and the emails on those deals" is two calls, or a search, not one SQL statement. Call tool_guidance before the first query, and confirm property names with search_properties (remote MCP server docs).

Confirmation in the chat can be switched off. The server-side tool asks for confirmation. Claude's article still tells an admin to open the connector's tool settings and set Write tools to Needs Approval. On Always allow, edits can land without a question in the chat. ChatGPT's article asks you to read the proposed changes before you confirm them, and it gives the same Needs Approval setting (Claude connector article, ChatGPT connector article). Keep that setting on Needs Approval.

Association labels are not checked. Conditional property rules and custom pipeline stage validations do apply on create and update. Association label validations do not (Claude connector article). A write can succeed on a link the record UI would have blocked. The ChatGPT connector article goes further and says custom validation rules, including pipeline stage and association label validations, are not applied when the connector creates or updates records (ChatGPT connector article). Try a deliberately invalid write on a test record before relying on either behaviour.

Sensitive Data draws the boundary in more than one place. Three HubSpot pages, read together on 16 Nov 2026, draw the boundary in different places, and the newer page wins where they conflict.

The current developer page says that with Sensitive Data turned on, conversation data is blocked through the MCP server, and that this block does not apply to the ordinary CRM APIs (remote MCP server docs). The April changelog said activity objects were blocked in that situation: calls, emails, meetings, notes and tasks (changelog).

The October 2026 changelog, still marked public beta, says a Super Admin can now allow read access that used to be closed. Claude and ChatGPT can be granted Sensitive Data properties and engagements. The remote MCP server can be granted engagements only. The same note names further assistants. Highly Sensitive Data properties stay restricted. The user still needs the CRM object or property permission, new permissions can take up to two hours to appear after a reconnect, and an existing connection has to be disconnected and authorised again (October 2026 changelog). Claude's article, updated 12 November 2026, describes the same grant: read-only, at install or reauthentication, and only if the user already has the property (Claude connector article).

So a portal with Sensitive Data on will not suddenly show the inbox. Logged emails and notes come back only after the grant, the reconnect, and a user who can already open those records. Conversation threads are the block the current developer page names on its own.

Scopes stay where you left them. New tools do not show up on an installed connector until someone reinstalls. On the Claude and ChatGPT apps, a Super Admin updates the data permissions and each user reconnects (remote MCP server docs, Claude connector article).

A few tools are tier-gated even when the server itself is on every account. AEO needs Marketing Hub Professional or Enterprise. Quote create and update, marked beta, need the manage revenue objects scope and Revenue Hub Professional or Enterprise. Accounts on free tools cannot create a custom pipeline. The pipeline tool can still edit the default pipeline HubSpot provides (remote MCP server docs).

Permissions: the part RevOps has to design

HubSpot states the rule in one place and then repeats it. Every action uses the authorising user's existing permissions. That user can only view and modify records they can already view and modify (remote MCP server docs, changelog). A super admin authorisation is a super admin session driven from a chat window, including billing, users and settings if those rights sit on the super admin. We create a user for the connector and give it the records the team is willing to put in a chat window.

Record access is per object, on all products and plans. The user permissions guide, updated 13 November 2026, sets View to all records, the team's records, or the user's own, with a checkbox for unassigned records. Edit adds None. Delete uses the same four choices. The MCP tools do not delete, so Delete can stay on None. Ownership follows the default owner property and any custom property of the HubSpot user field type. "Their team's" records means records owned by members of that user's teams.

Teams are how that middle option becomes real. HubSpot's teams article lists Professional and Enterprise across Marketing, Sales, Service, Data, Content, Smart CRM and Revenue Hub. Nested teams need an Enterprise subscription. A parent team can see what the teams under it own. A nested team cannot see everything the parent owns. Extra team membership needs Marketing, Sales or Service Hub Professional or Enterprise, and an extra team member sees the team's records without landing in that team's reports. If the connector user sits on a parent team, the grant is wider than the team name on the user screen.

Permission sets are how you reuse the grant. They require Marketing, Sales, Service, Data, Content or Revenue Hub Enterprise. A Super Admin creates and edits them. Someone with Add and edit users can assign a set, and only a set whose permissions they already hold. An account can hold up to 100 sets. Assigning a set replaces the user's individual permissions (permission sets). On a portal that is not on Enterprise, set the same View, Edit and Create rights on the user. The permissions guide itself is on all products and plans, so the narrow user does not wait on permission sets.

Property access is the layer people hope will hide one field. A Super Admin can mark a property private to super admins, visible to everyone, visible but editable only by super admins, or assigned to users and teams as view and edit, view only, or no access (property access). The article's subscription line does not name a product. It does say the control is incomplete: any user can still set a restricted property through HubSpot's API, or while creating a record by hand. The MCP server sits on those APIs. A property restriction is a poor wall around a write. If a field must not move, take Edit off the object, or do not grant the write. Some properties cannot be hidden at all, including contact email, first name, last name and lifecycle stage, and deal name, pipeline, stage and close date.

Field ownership, including who may see a sensitive property, belongs in the same map as the rest of the CRM. That map is the data governance guide. The connector user is one more named owner, with a written scope, held as its own login.

Someone also owns the connector credential. The client secret sits on the MCP connector details page. For the Claude and ChatGPT apps, a Super Admin approves the install, picks the data permissions, and decides who else may install it. App Marketplace access lets a user connect those apps without that prior approval (Claude connector article). Do not give the narrow user App Marketplace access, and keep the secret with the person who already owns the other CRM credentials. Writing that owner down is part of a normal HubSpot implementation, before the secret is pasted into a desktop app.

If the portal is mid-migration, connect after the object map has stopped moving. A connector writes into whatever the user can see that day. The sequence for the move is HubSpot migration. A review of the permission set before the first production write is the kind of pass we do as a second opinion.

The audit log is how you check the week after. Claude's article says create and update actions are recorded against both the user and the Claude connector, and that a Super Admin can see who connected, and when. ChatGPT's article records the same attribution for its connector. Viewing or exporting the log requires Super Admin permissions. The log is available on Starter, Professional and Enterprise of Marketing, Sales, Service, Data and Content Hub. Starter and Professional can filter the category to Login or Security Activity. Enterprise can filter further categories, including Approval, Content, Workflows and more. The log records actions a HubSpot user took. A form fill that no user made does not appear (audit log, Claude connector article). If the portal is not on Enterprise, read that article's subscription table before you promise the log will show CRM edits.

HubSpot also says that, when the MCP server is in use, it may collect summaries of tool calls, including the intent and whether the call succeeded, and that it takes steps to anonymize the names of people, companies and deals. After the data reaches Claude, Anthropic's terms apply. Accounts hosted in the EU have the HubSpot side routed through the EU data center. From there, the assistant vendor's terms decide where the copy lives (Claude connector article).

When to use MCP, and when to use a workflow instead

MCP fits a person who is asking, or making a small change they will read before it lands. What changed on this account, a note drafted and then logged after a yes, a single follow-up task: that is the shape. The confirmation step is the control.

A write that repeats, a write across a segment, or a write that has to run with nobody at the keyboard belongs in a workflow. HubSpot's own workflows are the native place, and the workflows playbook is how we structure them. When the job also has to call Clay, wait, retry and keep an error path, we put it in n8n. Building, testing and watching that agent is the agent guide. If the CRM data has to stay on infrastructure you operate, the EU self-host guide is the setup. An MCP session leaves HubSpot's data center and continues under the assistant vendor's terms. A workflow on a server you run does not take that second hop.

The records should already be fit to edit. A confirmed write onto a duplicate, or onto a deal with a blank close date, is still a write. The data quality guide is the hygiene that belongs in place first. Which CRM is a sound base when the question is HubSpot against the other platforms is the CRM platforms guide. The build, once it is more than a connector, sits with GTM engineering and AI automation.

A rollout order we would use

The remote server docs describe a test with the MCP Inspector against whichever account you pick in the OAuth screen. They do not describe a separate sandbox mode for this server. Run the order below on the account you mean to connect, as the narrow user, and finish the reads before the first write.

  1. Create the user. On Enterprise, put the grant in a permission set so the next portal can reuse it. Otherwise set View, Edit and Create on the objects this user should touch, and leave Delete on None. Put the user on the team whose records are in scope, and check whether that team is a parent.

  2. Create the MCP connector, or have a Super Admin approve the Claude or ChatGPT app and set its data permissions. Store the client secret with the other CRM credentials, under a named owner.

  3. Connect as that user. Run get_user_details. Read the user name and the object list before anyone asks a pipeline question. A wrong name means you stop and reconnect.

  4. Ask about a record the user should see, and about a record the user should not see. The second answer should fail or come back empty. That result is the test that the permission set is the boundary.

  5. Set write tools to Needs Approval. Make one change, read the proposed summary, confirm it, and open the record in HubSpot. If the assistant offers a bulk update on Claude or ChatGPT, keep it inside the 10-record cap those articles state.

  6. Leave it on real questions. After the first week, a Super Admin opens the audit log and filters to that user. Check the creates and updates the subscription actually records. On Starter or Professional the category filter is Login or Security Activity. Write down what the log can show. Then open the record in HubSpot and confirm the write you already know about.

  7. Widen last. A new object, Sensitive Data engagements, or a broader team all need a reconnect after the Super Admin changes the grant. Run get_user_details again, and repeat the hidden-record question, before anyone treats the wider user as the default.

FAQ

Is the HubSpot MCP server free, and which plans include it?

HubSpot's pages do not list a separate price for the remote server. The April changelog says it is generally available to all HubSpot accounts. The Claude connector is on all HubSpot products and plans, and it needs a paid Anthropic subscription: Pro, Max, Team or Enterprise. The ChatGPT connector is on all HubSpot tiers for customers who have an OpenAI account. Individual tools still have their own gates. AEO needs Marketing Hub Professional or Enterprise. Quote writes, in beta, need Revenue Hub Professional or Enterprise. Free tools cannot create a custom pipeline (changelog, Claude connector article, ChatGPT connector article, remote MCP server docs).

Can it delete records?

No. The Claude connector supports view, create and update. It does not support delete, including clearing a value such as a phone number. The Delete column on its object tables is empty. Deletion stays inside HubSpot (Claude connector article).

Is it safe to connect to production?

You connect the account you authorise, and the calls run as that user. HubSpot's guidance on the Claude connector is to review every proposed change, to set write tools to Needs Approval, and to have a person check the output, because the assistant can be wrong (Claude connector article). A narrow user, confirmation left on, and an audit log someone opens is the production shape we recommend. A super admin grant with Always allow is the shape to avoid.

What is the difference between the HubSpot MCP server and the developer MCP server?

The remote server at https://mcp.hubspot.com reads and writes CRM data for an account. The developer MCP server is local. You install it with hs mcp setup on CLI 8.2.0 or higher, and it helps you build apps and CMS content. HubSpot's changelog and both setup pages say the two servers are separate (remote MCP server docs, developer MCP setup, changelog).

Does it work with ChatGPT or Claude?

Yes. HubSpot publishes a Claude connector for web, desktop and mobile, and a ChatGPT connector. The remote server also accepts any MCP client that can complete OAuth with PKCE. Some content tools are only offered to the AI clients named on the developer page (Claude connector article, ChatGPT connector article, remote MCP server docs).

Why does it say it cannot see my emails and notes?

Emails and notes are engagements. With Sensitive Data turned on, they stay hidden until a Super Admin grants access. The October changelog says the remote MCP server can be granted engagements only, as read-only, and that Claude and ChatGPT can be granted Sensitive Data properties as well as engagements. The user still needs permission to those records, and has to reconnect. New permissions can take up to two hours to appear. Inbox and help desk threads are a separate object. The current developer page says those conversation threads are blocked through the MCP server when Sensitive Data is on (October 2026 changelog, remote MCP server docs, Claude connector article).

If you want the user, the scopes and the audit check settled before an assistant can write to the CRM, we do that as part of CRM and RevOps setup.

Talk to us