HubSpot MCP Server and Breeze Agent Builder Guide 2026

The HubSpot MCP server is a HubSpot-hosted remote server at https://mcp.hubspot.com that lets AI tools such as Claude, ChatGPT and Cursor read and write your HubSpot CRM data in plain language. It became generally available to all HubSpot accounts on 13 April 2026, connects with OAuth 2.1 and PKCE, and respects each user's existing HubSpot permissions. Breeze Agent Builder is the other direction: you build agents inside HubSpot, and since the Fall 2026 Spotlight you can describe the agent to Breeze Assistant and connect it to outside apps through MCP.

What changed with HubSpot and AI tools in 2026?

• 13 April: the remote HubSpot MCP server left beta and became available to all HubSpot accounts, with write access and activity history.
• 23 June: the HubSpot Agent CLI launched in public beta for bulk and scheduled agent work.
• 16 September (Fall 2026 Spotlight): an all-new Breeze Assistant that takes action, and Agent Builder (public beta) where you describe an agent in plain words.
• 16 October: HubSpot updated its guide to connecting outside apps to its AI agents through MCP.

This guide covers what each piece does, how to set up the HubSpot MCP server with Claude, ChatGPT and Cursor, where Breeze Agent Builder and the new Agent CLI fit, what it costs, and how to keep it secure.

Quick answer

HubSpot MCP server = a hosted endpoint (https://mcp.hubspot.com) that turns HubSpot CRM actions into tools any MCP client can call. Claude and ChatGPT users install the ready-made HubSpot connector; custom clients such as Cursor use an MCP auth app created under Development in HubSpot, with OAuth 2.1 and PKCE. Scopes are set by the tools and by the permissions you grant at install, not by hand. Breeze Assistant is on every plan; Agent Builder needs Professional or Enterprise and uses HubSpot Credits ($0.010 per credit). The Agent CLI (public beta) handles bulk and scheduled work. Start read-only, use least-privilege users, and keep a human approving writes.

What is the HubSpot MCP server, in plain English?

MCP (Model Context Protocol) is an open standard that lets an AI assistant discover and call tools in another system. HubSpot's remote MCP server exposes your CRM as those tools. You ask a question, the AI picks a tool, HubSpot runs it under your permissions, and the result comes back into the chat.

HubSpot announced the remote server as generally available on 13 April 2026, adding write capabilities, activity history, marketing content objects and organizational context. HubSpot hosts it, so there is nothing for you to run or maintain.

Do not confuse it with two similarly named tools:

• Remote HubSpot MCP server: for working with an account's CRM data, similar to using HubSpot's APIs.
• Developer MCP server: helps developers build apps and CMS assets locally on HubSpot's developer platform.
• MCP connectors in Agent Builder: let HubSpot's own agents call outside apps. This is the reverse direction and is covered below.

What can Claude or ChatGPT actually do in HubSpot?

HubSpot's developer documentation lists the following. Tool availability varies by subscription, user permissions and account configuration.

What it can look up

• CRM records: contacts, companies, deals, tickets, line items, quotes, invoices, orders, carts, products, subscriptions and segments (lists)
• Marketing and content: campaigns, landing pages, blog posts, site pages and marketing events
• Activities: calls, meetings, notes, tasks and emails

What it can create or change

• CRM records: create and edit contacts, companies, deals, tickets, leads, line items, products, custom object records and more, respecting conditional field logic and pipeline stage validations
• Activities: log calls, emails, meetings, notes and tasks
• Content: create, edit and publish landing pages, website pages and blog posts
• Campaigns, marketing email drafts, pipelines, custom properties and static segments
• Quotes (beta): needs the manage revenue objects optional scope and Revenue Hub Professional or Enterprise
• AEO: create tracked prompts and act on brand recommendations, with Marketing Hub Professional or Enterprise

After connecting, run the get_user_details tool to see exactly which tools and objects your account can use.

How do I connect HubSpot to Claude, ChatGPT or Cursor?

First, a Super Admin (or a user with App Marketplace Access) must approve the connector. For everyone else, the admin reviews and approves the app, chooses which optional data permissions it can access, and decides who may install it.

How to connect HubSpot to Claude

1. Click your profile icon, then Settings, then Connectors.
2. Click Browse, search for HubSpot and click Connect.
3. Log in to HubSpot.
4. Select the HubSpot account and confirm the permissions the connector can access.
5. Start a new chat and ask about your contacts, deals or tickets.

Claude Enterprise admins can limit the connector to company-provisioned accounts by turning on verified domain restrictions.

How to connect HubSpot to ChatGPT

1. Click your profile icon, then Settings, then Apps.
2. Select HubSpot and click Connect, then Continue to HubSpot.
3. Log in and choose the HubSpot account.
4. Select the permissions to allow and click Connect App.
5. Return to the chat and start prompting.

HubSpot notes that the Claude and ChatGPT connectors require a paid Claude or ChatGPT plan.

How to connect HubSpot to Cursor (or any MCP client)

1. In HubSpot, go to Development and create an MCP auth app (HubSpot calls this an MCP connector). HubSpot generates the client ID and secret.
2. Set a redirect URL that matches your client.
3. In Cursor (or any client that supports OAuth with PKCE), add a remote MCP server pointing to https://mcp.hubspot.com with the client ID and secret.
4. Sign in to HubSpot when prompted and grant permissions.
5. Run get_user_details to confirm what is available.

Why does it ask for so many permissions?

Everything runs as the person who connected it, so the AI can only see and change what that user can in HubSpot.

• OAuth 2.1 with PKCE is required for every connection.
• You do not define scopes by hand. They come from the tools available at install time and the permissions the user grants.
• When HubSpot adds tools, scopes can change. Installed apps may show REQUIRES_REAUTHORIZATION, and users must disconnect and reconnect to grant the new scopes.
• If sensitive data is turned on in your account, activity objects (calls, emails, meetings, notes, tasks) are blocked through the MCP server.

What did HubSpot announce at the Fall 2026 Spotlight?

At the Fall 2026 Spotlight on 16 September 2026, HubSpot introduced an all-new Breeze Assistant that takes action, assigns the right agents to a task and works from your CRM context. It also announced a self-updating Smart CRM, Context Home, Marketing Studio and Revenue Hub. For builders, the key changes were:

• Build agents in Breeze Assistant: open Agent Builder from Agent Hub, click Create and describe the agent in plain language. Breeze Assistant proposes a goal, tools and knowledge sources, may ask clarifying questions, then opens the agent ready to test or publish. Agent Builder is in public beta.
• Scheduled Prompts: Breeze Assistant can run a prompt daily, weekly or monthly and deliver the result as a new chat thread.
• MCP server component for apps: developers can add an mcp-server component (platformVersion 2026.09) so their app's tools appear in HubSpot Agents automatically. Marketplace apps need HubSpot review.
• Build with AI docs: a new developer docs section covering AI connectors, the MCP server, Agent CLI and Breeze Assistant.

Can HubSpot's own agents use Slack, Gong or Notion?

Agent Builder lets you create custom agents that analyze data, generate outputs and take actions based on your processes. You define what the agent does, what data it can reach and how it responds. Creating agents needs Agent Builder permissions, plus whatever permissions the task needs (for example, Edit and Publish to publish a landing page).

HubSpot's knowledge base article on connecting apps to HubSpot's AI agents, updated 16 October 2026, explains that agents can reach external systems through MCP without custom code. Supported apps currently are Amplitude, Asana, Atlassian, Box, Canva, Fathom, G2, Gmail, Gong, Google Calendar, Google Chat, Google Drive, Linear, Notion, Slack, Xero, Zapier and Zoom (beta). Each app has its own configuration requirements.

What's the difference between the MCP server, Agent Builder and the Agent CLI?

Remote HubSpot MCP server

• Best for conversational, human-in-the-loop work from Claude, ChatGPT or Cursor
• Answering questions, pulling insights and making small updates in real time
• Works with any MCP client that supports OAuth with PKCE

Breeze Assistant and Agent Builder

• Best when the agent should live inside HubSpot, triggered by your CRM processes
• Can reach outside apps through MCP connectors
• Needs Professional or Enterprise for Agent Builder, and consumes HubSpot Credits

HubSpot Agent CLI (public beta)

• Announced in public beta on 23 June 2026; built for agents in environments such as Claude Code, Claude Cowork and OpenAI Codex
• Best for bulk, scheduled and background work without a person in the loop
• Covers CRM objects, pipelines, properties, associations, workflows, activities and reports
• Every write command supports --dry-run, and a local history logs destructive operations
• HubSpot says CLI calls can be more token-efficient than MCP because no full tool schema loads into context

Is the HubSpot MCP server free?

HubSpot does not list a separate fee for the remote MCP server. What you pay depends on your HubSpot plan, your AI tool and credit use:

• Breeze Assistant: included on all plans, including the free CRM. Creating an agent or using workflows needs Professional or Enterprise.
• Smart CRM seats (published starting prices): Starter from $15 per seat per month, Professional from $50, Enterprise from $75.
• HubSpot Credits: $0.010 per credit, via Pay-as-You-Go or capacity packs of 1,000 credits for $10. Credits reset monthly and do not roll over.
• Included credits: 500 (Starter), 3,000 (Professional) and 5,000 (Enterprise) for Smart CRM and most hubs; Data Hub and Customer Platform include 500, 5,000 and 10,000.
• AI tool: the Claude and ChatGPT connectors need a paid plan on those tools.

Check HubSpot's rate sheet for how many credits each agent action uses before rolling out widely.

Should you use MCP, Agent Builder or the CLI? A quick checklist

• A person asks questions and approves changes in Claude, ChatGPT or Cursor? Use the MCP server or the official connector.
• The work should run inside HubSpot, triggered by records or schedules your team already uses? Use Agent Builder (Professional or Enterprise).
• Hundreds of records, runs overnight, nobody watching? Use the Agent CLI, with --dry-run first.
• The agent needs data from Slack, Gong, Notion or another supported app? Use Agent Builder with an MCP connector.
• You need tight control over keys and permissions, or an unsupported system? Consider a custom build.

Common mistakes when connecting HubSpot to Claude or ChatGPT

• Approving write access in Claude but not in HubSpot. In a HubSpot Community thread, write tools stayed at REQUIRES_REAUTHORIZATION because App Governance restricted them. A Super Admin had to turn them on under Settings, Integrations, Connected Apps, Approved apps, Manage access, and the user then reconnected.
• Expecting one person to get extra access. Connector data permissions are set for the account, and each user is still limited by their own HubSpot permissions.
• Connecting with an admin account for everyday use. The AI inherits that user's reach. Use a user with only the access the job needs.
• Expecting big bulk edits in chat. HubSpot says the Claude connector creates or updates 10 records at a time. Use the Agent CLI for bulk work.
• Asking about draft pages. For website pages, landing pages and blog posts, the Claude connector only sees published data; drafts show metadata only.
• Forgetting sensitive data settings. With sensitive data on, calls, emails, meetings, notes and tasks are blocked through MCP.
• Ignoring new scopes. When HubSpot adds tools, reconnect, or new features will not appear.

What are the limits?

• Tools vary by subscription and permissions, so two users may see different capabilities.
• Sensitive data settings block activity objects through MCP.
• Scope changes require users to reconnect.
• Some write tools (quotes, AEO) need specific Professional or Enterprise hubs.
• Agent Builder and Agent CLI are in public beta, so features may change.
• Free accounts cannot create custom pipelines through MCP, only edit the default one.

Is it safe to give AI access to my HubSpot CRM?

1. Approve centrally: have a Super Admin approve the connector, restrict optional data permissions and limit who can install it.
2. Least privilege: connect with users whose HubSpot permissions match the use case, because every action runs as that user.
3. Start read-only: grant only the permissions needed for reporting first, then add write access deliberately.
4. Keep a human in the loop: require confirmation in your AI tool for creates, updates and publishing.
5. Test in a sandbox: use --dry-run for Agent CLI writes and test agents before publishing.
6. Watch credits: set credit limits per feature and monitor usage.
7. Review regularly: audit connected apps, re-check scopes after reauthorization and remove unused connections.

For a fuller framework, see our guide on how to evaluate AI agents. If you also run Zoho, compare with our Zoho CRM MCP server and Zia Agents guide, or see how the three platforms stack up in Zoho vs HubSpot vs Salesforce AI agents.

What are people actually using it for?

• Summarize a deal, its last calls and open tasks before a meeting
• Log notes and create follow-up tasks straight from a chat
• Find stale deals or tickets and draft next steps for review
• Draft a marketing email or landing page for a person to approve
• Run a weekly pipeline summary with Scheduled Prompts
• Build an Agent Builder agent that qualifies new contacts against your criteria

Insyrge's HubSpot consulting and AI agents development teams can scope these with you.

Sources

• Remote HubSpot MCP server is now generally available (13 Apr 2026)
• Integrate AI tools with the HubSpot MCP server
• Using the HubSpot MCP server
• HubSpot connector for ChatGPT
• HubSpot connector for Claude
• Set up and use the HubSpot connector for Claude
• HubSpot Community: write tools stay REQUIRES_REAUTHORIZATION
• Fall 2026 Spotlight: developer updates
• Fall 2026 Spotlight announcement (16 Sep 2026)
• HubSpot Agent CLI public beta
• Connect apps to HubSpot's AI agents (updated 16 Oct 2026)
• Create and customize agents in the agent builder
• Use Breeze Assistant
• HubSpot Credits
• HubSpot Products & Services Catalog
• HubSpot Smart CRM pricing

Frequently asked questions

Is the HubSpot MCP server free?

HubSpot lists no separate fee for it, and it is available to all HubSpot accounts. Your AI tool may need a paid plan, and agent features in HubSpot use HubSpot Credits.

What is the HubSpot MCP server URL?

https://mcp.hubspot.com. Clients connect with OAuth 2.1 and PKCE.

Do I need to configure OAuth scopes?

No. Scopes come from the server's tools and the permissions you grant during install. Reconnect if HubSpot adds new scopes.

Can the AI see all my HubSpot data?

No. Every action respects the signed-in user's HubSpot permissions.

Does it work with Cursor?

Yes. Create an MCP auth app under Development in HubSpot and add https://mcp.hubspot.com to Cursor with its client ID and secret.

What is the difference between the MCP server and Agent Builder?

The MCP server lets outside AI tools use HubSpot. Agent Builder creates agents inside HubSpot, which can call outside apps through MCP connectors.

Why can't Claude write to HubSpot even though I approved it?

Usually a Super Admin has not enabled the write permissions for the connector in HubSpot's approved apps settings. Turn them on, then disconnect and reconnect.

When should I use the Agent CLI?

For bulk, scheduled or background work run by an agent. For conversational, human-reviewed work, use the MCP server or AI connectors.

Need help with the HubSpot MCP server and Breeze agents?

Insyrge will help you set it up end to end.

We set up the HubSpot MCP server and Breeze agents for you: connector approval, the connection to Claude, ChatGPT or Cursor, least-privilege permissions, agent design, credit controls and testing before anything touches live data. Book a call with Insyrge.