Connecting an AI Agent to HubSpot with MCP: What the First-Party Server Does Not Solve

The problem: 12 tools that solve connection, not meaning

HubSpot shipped its Remote MCP Server to general availability on April 13, 2026. It connects Claude, ChatGPT, Cursor, or any MCP-compatible AI client to a HubSpot portal over OAuth 2.1 with PKCE, authenticated against the mcp.hubspot.com endpoint. It is free across all hubs and tiers. It exposes 12 tools with read and write access across standard CRM objects — contacts, companies, deals, tickets, products, line items, invoices, quotes, orders, carts, subscriptions, segments — and engagement history (calls, emails, meetings, notes, tasks). It also reads campaign metrics, landing pages, website pages, and blog posts. HubSpot's official documentation confirms every action respects the connected user's existing HubSpot permissions — it is not a backdoor.

This is a genuine product, not a demo. For a sales rep who wants to ask Claude "summarize all open deals in the 'Decision maker bought in' stage with deal value over $1,000," the first-party server handles it. HubSpot also shipped a one-click connector for Claude (July 16, 2026) that lets any HubSpot user with a paid Anthropic subscription connect their CRM to Claude's chat interface without writing code. The setup takes minutes.

The problem is not what the first-party server does badly. The problem is what it does not do at all. Daeda Tech's analysis (April 14, 2026, updated May 22, 2026) names the gaps directly: "The gaps are not about what the official MCP does badly — they are about what it does not do at all." None of these are bugs. They are product scope decisions. HubSpot shipped a solid, safe starting point. But for a mid-market B2B company running custom objects, workflow automation, or multi-portal operations, the first-party server covers the easy half and leaves the hard half to a custom module.

The six capability gaps

Daeda Tech and Scalekit's comparison (June 2, 2026) document the gaps from production use. They map to the same structural pattern that appears in the NetSuite MCP module analysis: the vendor's first-party connector solves the connection problem. It does not solve the semantic layer problem — the gap between what the data says and what the business means.

1. No custom objects

The Remote MCP Server exposes standard CRM object types only. If your portal relies on custom objects for renewals, partnerships, product usage tracking, or any industry-specific data model, the official MCP cannot see or touch them. Scalekit confirms: "Enterprise HubSpot accounts are rarely vanilla — professional services firms, healthcare tech companies, and revenue ops teams routinely build core data models on custom objects." The gap is underdocumented: no error code signals "this is a custom object." The agent simply cannot access the data. The HubSpot community forums documented this in March 2026 — developers discovered it through troubleshooting, not documentation. The only workaround is the direct API, which means the agent needs a custom module to reach it.

2. No reviewable write plans

The first-party server executes writes immediately via manage_crm_objects. There is no drafting, no batch review, no undo-as-a-batch for multi-step changes. A sales rep who asks Claude to "move all deals in the 'Demo stage' to 'Proposal sent'" gets immediate, irreversible mutations. For a RevOps team that needs to review bulk pipeline changes before they commit — because a wrong stage move distorts forecast reporting and triggers downstream workflow automation — the lack of a review gate is a production risk. Daeda AI calls this "Write Plans with Human Review" — AI drafts a structured plan, a human reviews and approves it, then the plan executes. The first-party server has no equivalent.

3. One portal per connection

OAuth 2.1 authenticates one user to one portal. An agency or consultant managing five HubSpot portals needs five separate OAuth connections, five token refresh cycles, and five context switches in the AI client. There is no workspace model. For a B2B services company that manages multiple client HubSpot instances, this is an operational constraint that does not scale. A custom module can handle multi-portal routing internally — the agent calls get_deals(portal_id, ...) and the module resolves the correct credentials, token, and endpoint. The first-party server cannot.

4. No system-level design

The first-party server is record-level only. It cannot design pipelines, lifecycle stages, workflow logic, or list criteria conversationally. A RevOps leader who wants to ask an agent "create a new pipeline stage called 'Procurement Review' between 'Qualified' and 'Proposal Sent' and move all deals above $50K into it" cannot do it through the MCP server. The direct HubSpot API supports Workflow Automation API v4 and pipeline management — but the MCP server does not expose those endpoints. System design is a direct-API operation, which means it requires a custom module to reach from an agent.

5. Every query hits the API live

The first-party server has no local data layer. Each tool call round-trips to HubSpot servers. Daeda Tech notes: "Latency and pagination accumulate for large analyses." The search_crm_objects tool returns up to 200 results per page. A cross-object analysis across thousands of records means paginating through dozens of API calls, each adding latency, each subject to the rate limit. For a quarterly pipeline review that pulls every deal, its associated contacts, their engagement history, and their company properties, the live-API-only model produces a slow agent that interrupts mid-thought to wait for the next page. A custom module with a managed data layer syncs portal data to a local database and runs cross-object queries in seconds — no per-question API round-trips, no pagination mid-thought.

6. The sensitive-data constraint

If a HubSpot account has the "Sensitive Data" toggle enabled — common in healthcare and financial services, required for accounts handling personal health information — the MCP server blocks all engagement objects: calls, emails, meetings, notes, and tasks. CRM objects remain accessible, but the engagement history that gives a contact or deal its context disappears. The official documentation confirms this directly: "If Sensitive Data is enabled, activity objects (calls, emails, meetings, notes, tasks) are blocked from MCP server access." The Claude connector setup guide repeats the same constraint. The direct CRM API, with specific scopes, can access sensitive data properties — but the MCP server cannot. A healthcare B2B company that needs an agent to read call notes on a customer record is blocked at the protocol layer, not the permission layer.

Authentication: the headless agent problem

The Remote MCP Server enforces OAuth 2.1 with PKCE exclusively. There is no private app token path. Scalekit's analysis names the consequence: "The direct API supports both OAuth 2.0 and private app access tokens — the latter being the only viable auth method for headless, scheduled, or background agents that can't complete a browser-based consent flow."

PKCE requires a browser-based consent flow — a human clicks "Allow" in a redirect URL, HubSpot issues an authorization code, the client exchanges it for tokens. Refresh tokens are single-use and rotate on every refresh. This is secure for interactive use. It is unworkable for a background agent that runs at 2 AM to sync overnight deal changes to a data warehouse, or a scheduled workflow that checks for stalled deals every hour and creates follow-up tasks. There is no human to click "Allow" when the token expires.

The direct HubSpot API supports private app access tokens — scoped bearer tokens with no redirect, no browser, no consent flow. These are what headless agents and scheduled workflows actually need. A custom MCP module can authenticate via private app tokens for unattended operations and via OAuth 2.1 for interactive agent sessions — the module handles the auth path internally, the agent calls get_deals and does not know or care which credential is in use.

The rate limit compounds this. HubSpot's API usage guidelines set 100 requests per 10 seconds for private apps on Free/Starter, 190 per 10 seconds on Professional/Enterprise. The same limit applies to MCP server requests — they run against the same CRM Search API underneath. An agent that fires 30 tool calls in parallel against a Free/Starter portal will fail a third of them. The first-party server returns a 429 with no structured retry guidance beyond what the MCP client implements. A custom module enforces per-tool rate limiting — each tool declares its own limit, the backbone throttles, and the agent receives a structured 429 with a Retry-After header rather than a crash.

What a custom MCP module provides

The module pattern follows the MCP Module Code Standard: every tool has a typed input schema, a typed output schema, a rate limit, an audit log, and an error contract. The agent calls tools by name with structured arguments, not free-form API calls against raw endpoints.

For HubSpot, the custom module fills the six gaps:

Custom objects. The module exposes typed operations on custom object schemas — get_renewal_record(renewal_id), search_custom_objects(object_type, filters), update_partnership_status(partnership_id, status). Each tool's schema encodes the custom object's properties, associations, and business meaning. The agent reaches custom object data through the module, not through a workaround.

Reviewable write plans. The module drafts a structured plan for multi-step changes — "move 47 deals from 'Demo' to 'Proposal Sent,' update the close date on 12 of them, create follow-up tasks for the deal owners" — and routes it to a human reviewer before execution. The plan is a typed object, not a free-form text blob. The reviewer approves, rejects, or modifies. The module executes only the approved plan and logs every change.

Multi-portal routing. The module accepts a portal_id parameter on every tool call and resolves the correct credentials, token store, and endpoint internally. The agent does not manage OAuth sessions. A single agent invocation can query deal data across five portals in one pass.

System-level design. The module exposes pipeline management, lifecycle stage configuration, and workflow automation as typed tools — create_pipeline_stage(pipeline_id, label, display_order, probability), update_lifecycle_stage(contact_id, stage), enroll_in_workflow(contact_id, workflow_id). These map to the HubSpot Automation API v4 and pipeline management endpoints that the first-party server does not expose.

Managed data layer. The module syncs portal data to a local database on a schedule — deals, contacts, companies, engagements, custom objects — and runs cross-object queries against the local copy. The agent asks "show me all deals that have been in 'Proposal Sent' for more than 14 days with no engagement in the last 7 days" and the module returns the answer in seconds, not minutes of paginated API calls.

Sensitive data access. The module authenticates via private app tokens with the specific scopes needed to read sensitive properties — not through the MCP server's blocked path. The agent reads call notes on a healthcare customer record because the module uses the direct API with the correct scope, not the first-party server's blanket block.

The semantic layer: what the first-party server does not encode

The pattern is the same as the NetSuite analysis. The first-party connector gives the AI access to records. A custom MCP module gives the AI understanding of what those records mean. This is the semantic layer — typed schemas that tell the agent which deal stages map to "won revenue" for this company's forecast, which lifecycle stages constitute "qualified lead" for this marketing team's SLA, which custom object properties are "renewal value" for this customer success team's churn model.

Consider a pipeline analysis. The first-party server exposes search_crm_objects with filter groups. An agent can find all deals in a given stage. What it cannot tell the agent is that for this company, the "Closed Won" stage in the Sales pipeline counts toward revenue, but the same stage in the Renewals pipeline does not — renewals are counted under a separate revenue line. The agent that does not know this distinction produces a forecast that double-counts. The module's typed schema encodes the distinction: get_revenue_pipeline_summary(period, pipeline_ids=["sales"], exclude_pipeline_ids=["renewals"]). The agent receives a correct answer because the question it asks is the question the business means.

Or consider lifecycle stages. The first-party server can read a contact's lifecycle stage. It cannot tell the agent that for this company, a contact becomes "Marketing Qualified Lead" only after filling out a form with a company size field above 50 employees — a rule that lives in a custom workflow, not in the lifecycle stage definition. The module encodes the rule in its tool schema: get_qualified_leads(since_date, min_company_size=50, source="form_submission"). The rule is in the schema, not in the prompt.

Why this generalizes

The HubSpot pattern — a first-party MCP server with 12 tools that covers standard objects, a semantic layer gap that the vendor does not provide, an authentication constraint that blocks headless agents, and a rate limit that breaks naive parallel calls — is the same structure that appears across the CRM and ERP landscape:

• NetSuite has a first-party AI Connector Service with an accuracy gap — Oracle's own FAQ warns "AI may hallucinate. Always validate results against source data." The semantic gap is which GL accounts constitute "revenue" for this business. The NetSuite MCP module analysis covers this in depth.
• Shopify has a first-party Storefront MCP and a Universal Commerce Protocol with Google, but the B2B path — customer-tier pricing, bulk RFQ quoting, inventory holds against NetSuite, order attribution — is not in the first-party surface. The Shopify connector analysis covers this.

The Anthropic 2026 State of AI Agents Report (500+ technical leaders, real-world implementations at Novo Nordisk, Doctolib, L'Oréal, Shopify) identifies integration with existing systems as the number one barrier to agent adoption — 46% of organizations cite it, ahead of data access (42%), security (40%), and model intelligence. 47% use a hybrid build-and-buy approach: not entirely pre-built, not all in-house, but a platform they extend with custom code. The first-party MCP servers are the "buy" half. The custom module is the "build" half. The teams that ship production agents in 2026 are the ones that do both — the first-party server for what it covers, the custom module for what it does not.

HubSpot shipped a solid first-party server. For standard-object lookups and simple updates, it is enough. For custom objects, reviewable writes, headless authentication, multi-portal operations, system-level design, and sensitive-data access, the custom module is the production path. The MCP Module Code Standard defines the structure. The HubSpot connector is the reference implementation for the CRM case — the one where 12 tools get you started, and the semantic layer gets you to production.

---

A B2B services company running HubSpot across five client portals, with custom objects for renewals and partnerships, workflow automation for pipeline management, and a quarterly forecast that depends on correctly distinguishing sales revenue from renewal revenue, gets an agent that resolves custom object records, drafts reviewable write plans for bulk pipeline changes, authenticates headless for scheduled syncs, routes across portals in a single session, and encodes the revenue-stage distinction in typed schemas — with every tool call logged and every exception routed to a human reviewer. That build is Phase 2-3 of the four-step method and is typically live in 5-8 weeks.

Request a scoped build. One-week discovery. You get a system inventory, workflow map, and fixed scope — whether or not you build with us.