HubSpot MCP vs HubSpot API for AI Agents

TL;DR

• HubSpot ships two entirely separate MCP servers with different purposes.
  • The remote CRM MCP (^{mcp.hubspot.com}, GA April 13, 2026) is for agent-to-CRM data access.
  • The local Developer MCP (GA February 19, 2026) is for building HubSpot apps and CMS assets via the CLI.
• For agent workflows, you want the remote server. They are not interchangeable.
• The remote MCP covers standard CRM objects and engagement history with full read/write access, but has a confirmed, underdocumented gap: custom objects are not supported. Any HubSpot account with a non-standard data model exposes this immediately, and the only workaround is the direct API.
• The MCP server enforces OAuth 2.1 with PKCE exclusively. No private app token path. 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.
• Neither path solves per-user credential isolation for multi-tenant agents. MCP gives you one OAuth token per user. The direct API gives you one credential per user. At scale, storage, refresh, and revocation are your infrastructure problems regardless of which path you chose.
• Scalekit's HubSpot connector handles token storage, OAuth lifecycle, and revocation for either path, so the MCP vs API decision doesn't change your auth infrastructure.

Your agent needs to touch HubSpot. Maybe it's a deal intelligence tool that surfaces pipeline context in real time. Maybe it's a background enrichment job that runs every night against a list of prospects. Maybe it's both, depending on which tenant you're serving. HubSpot now ships two distinct official MCP servers and a full REST API, and the choice between them is not cosmetic. Each path puts you on a different auth model, locks you into a different capability envelope, and creates different operational surface area in production. The non-obvious part: the gap between them matters differently depending on what your agent actually does.

What HubSpot MCP and the HubSpot API actually are

The remote HubSpot MCP server

HubSpot's remote CRM MCP server went GA on April 13, 2026. It's a HubSpot-hosted server at mcp.hubspot.com. Any MCP-compatible client can connect to it over Streamable HTTP and get natural language access to CRM data, authenticated via OAuth 2.1 with PKCE.

The setup path is distinct from standard OAuth app registration. You create an "MCP auth app" inside HubSpot's developer dashboard (Development > MCP Auth Apps), HubSpot generates OAuth credentials automatically, and you use those credentials to authenticate any PKCE-capable MCP client to mcp.hubspot.com. Scopes are assigned automatically at installation time based on the tools the MCP server currently exposes. You do not define them explicitly.

By the way, HubSpot's Developer MCP server (hs mcp setup, local, CLI-based, GA February 19, 2026) is a completely different product. It gives agentic coding tools like Claude Code, Cursor, and VS Code access to HubSpot's developer platform for building apps and CMS content. It is not for reading or writing CRM data. The two come up together in search results and documentation and are easy to conflate. For agent-to-CRM workflows, only the remote server matters.

Official docs: developers.hubspot.com/mcp

The HubSpot CRM API

HubSpot's REST API covers the full platform surface: standard CRM objects, custom objects, marketing content, workflow automation, sequences, the Conversations API (inbox, threads, messages), analytics, and more. The surface area is large: HubSpot publishes versioned endpoints across dozens of API categories, and the platform has continued expanding through 2025 and 2026 (the Conversations API moved to public beta in March 2026; custom object stage calculated properties shipped in May 2026).

Two auth paths exist for HubSpot API

OAuth 2.0 is the right choice for multi-tenant apps where each customer installs your application into their own HubSpot account: the standard authorization code flow, user-delegated, scoped at the app level. Private app access tokens are the right choice for single-portal internal integrations: scoped bearer tokens generated inside a specific HubSpot account, no redirect required, no browser, headless-friendly. Private app tokens are what background agents and scheduled workflows actually need.

Rate limits

100 requests per 10 seconds for private apps. The same rate limit applies to MCP server requests — they run against the same CRM Search API underneath.

Official docs: developers.hubspot.com/docs/api-reference

Comparing them where it matters for agents

What your agent can actually do

The custom object gap is the most operationally significant one and the most likely to surface in production without warning. HubSpot's community forums documented this in March 2026 — developers discovered the gap only through troubleshooting, not from the documentation. No error code signals "this is a custom object." The agent simply can't access the data.

This matters more than it sounds. Enterprise HubSpot accounts are rarely vanilla. Professional services firms, healthcare tech companies, and revenue operations teams routinely build their core data models on custom objects — proprietary deal types, custom lifecycle stages, non-standard association types. If your agent is connecting to a HubSpot instance that has been configured for a specific vertical, there's a meaningful probability the data you need lives in objects the MCP server doesn't expose.

The sensitive data block is the other gap worth naming explicitly. When 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 activity objects: calls, emails, meetings, notes, and tasks. This restriction does not exist in the standard CRM API. An agent that works correctly against a standard account will fail silently against a Sensitive Data account — same tool call, different outcome.

The auth path each one puts you on

• MCP forces you onto OAuth 2.1 with PKCE, full stop.

Every user who connects your agent to their HubSpot account completes a browser-based consent flow. HubSpot generates a short-lived access token and a rotating refresh token — single-use, meaning each token refresh produces a new refresh token and the previous one is immediately invalidated. If your storage layer doesn't handle that atomically, you end up in a state where the old refresh token is gone and the new one wasn't persisted. The agent deauthenticates mid-execution.

• The scope assignment model adds another production constraint.

When HubSpot updates the MCP server and adds new tools, scopes change. Users who installed your app before the update have a different scope set than users who install after. To access new scopes, every existing connected user must disconnect and reconnect. There's no silent scope expansion. For a multi-tenant agent managing N customer connections, a MCP server update is an N-user re-authorization event.

• The direct API gives you two distinct paths.

OAuth 2.0 follows the standard authorization code flow — user-delegated, per-account credential, short-lived access tokens with refresh. The right model for a multi-tenant B2B product where each customer installs your application into their HubSpot account. Private app access tokens are static bearer tokens scoped at creation time, requiring no redirect and no browser interaction. These are what scheduled jobs, background enrichment pipelines, and nightly sync agents actually need — the agent runs at 2am with no user in the loop, and the token is there.

The structural reality for multi-tenant agents: both paths produce a per-user credential. MCP gives you an OAuth token per user. The direct API gives you an OAuth token or private app credential per user. In neither case does the path itself solve how you store those credentials, how you refresh them, or how you revoke them when a user disconnects. At scale, that's an infrastructure problem independent of which transport you chose.

What you own in production

With the remote MCP server,

• HubSpot manages the endpoint, the tool schemas, and the mapping from natural language to CRM operations.
• You get a curated set of tools with predictable schemas; no normalization work on your side for the objects the server covers.

What you still own: token storage, refresh token rotation (with atomicity requirements, as noted above), revocation, and tenant isolation. You also inherit a dependency on HubSpot's tool schema decisions. When the MCP server adds or changes tools, your agent's available scope changes without your code changing. That's convenient when tools are added; it's a breaking change if a tool is removed or its parameter contract changes.

With the direct API, you own everything.

• Endpoint versioning, schema normalization, rate limit handling, retry logic, error differentiation, and the full token lifecycle for whichever auth path you chose.
• The surface area is larger.
• The benefit is that your agent's behavior is determined entirely by your code, not by HubSpot's decisions about which tools to expose or when to rotate the scope set.

One practical note on rate limits: MCP requests and direct API calls share the same limit. 100 requests per 10 seconds for private apps. If your agent makes high-frequency calls — enrichment pipelines, bulk contact updates — the MCP server buys you nothing on throughput. The ceiling is the same.

When to use MCP, when to use the API

Use the HubSpot remote MCP when:

• Your agent is user-interactive — a sales rep's assistant, a deal intelligence tool that surfaces context during active sessions, an account review agent that runs in a live conversation.
• Your HubSpot accounts use only standard CRM objects. No custom objects, no custom sensitive data properties, no activity data in accounts with Sensitive Data enabled.
• You're building a prototype or an agent where tool discovery and reduced integration surface area matter more than capability completeness.
• Your agent's workflow maps naturally to engagement history alongside CRM records in a single query — the MCP server handles this natively and cleanly.

Use the direct API when:

• Your agent runs headlessly or on a schedule — background sync, nightly enrichment, batch pipeline updates, scheduled reporting — where a browser OAuth consent flow is not possible. The private app token path exists specifically for this.

That said, if you're using a token vault like Scalekit, the headless constraint on the MCP path largely disappears: the user completes the OAuth consent flow once, Scalekit stores and manages the token, and every subsequent background execution retrieves credentials from the vault with no browser and no user in the loop. The reason to still prefer the direct API's private app token for pure headless automation is operational simplicity — a private app token doesn't rotate, so there's no atomic refresh write requirement, no expiry to manage, and no risk of losing the credential mid-execution if a refresh write fails.

• Your HubSpot accounts use custom objects. This is a hard stop for the MCP server; there's no partial workaround.
• You need workflow or automation management, sequence enrollment, or write access to marketing content (campaigns, landing pages, blog posts).
• You're serving enterprise accounts with Sensitive Data enabled and your agent needs access to call logs, email history, or meeting records.
• You're building a multi-tenant B2B product where each customer's HubSpot instance has its own data model and you need explicit scope control, not auto-assigned scopes tied to HubSpot's server update schedule.

The credential problem that exists on both paths

Both paths produce a credential per user.

• MCP produces a rotating OAuth 2.1 token with single-use refresh semantics.
• The direct API produces either an OAuth 2.0 token with a refresh token or a static private app access token.

The path you chose changes the token type and the token lifecycle — it does not change the underlying infrastructure requirement.

In a multi-tenant B2B agent, which is the default deployment model for most production use cases, you have N users across N HubSpot accounts. Each has their own credential. Each credential needs to be stored encrypted and isolated per tenant. Each OAuth credential needs to be refreshed before expiry, not after — waiting for a 401 to trigger refresh in a background agent means the agent fails silently and the next scheduled run is the first indication anything went wrong. And when a user offboards or disconnects their HubSpot integration, their credential needs to be revoked cleanly, not just orphaned in your storage layer.

The MCP path adds one layer of complexity here that the direct API doesn't: single-use refresh token rotation means your storage write and your token exchange must be atomic. A missed write during a network hiccup leaves you with an invalidated refresh token and no replacement. Handling this correctly is not trivial.

Scalekit's HubSpot connector handles the OAuth lifecycle for both paths — token storage, proactive refresh, rotation handling, and revocation. So, with Scalekit, the MCP vs API decision doesn't change what you build for auth infrastructure. The connector works the same way regardless of which transport your agent uses.

Which one to build against

With Scalekit, the decision is primarily a capability question, not an auth question.

• If your agent is user-interactive and your HubSpot accounts are standard, the remote MCP is the faster path. Lower integration surface area, clean per-user OAuth semantics, and HubSpot handles the tool schema complexity. The gaps in custom objects, workflow management, and marketing content writes won't matter for most CRM-assistant use cases.
• If your agent runs in the background, connects to accounts with custom data models, or needs the full HubSpot API surface — automation, sequences, the Conversations API, sensitive data — the direct API is the only path. The MCP server's capability set is real and growing, but it's built on the CRM Search API and intentionally scoped to the operations HubSpot considers the core CRM workflow. Anything outside that envelope requires direct API access.

For multi-tenant B2B products, the credential management requirement is the same on both paths. That's the infrastructure problem worth solving once, correctly, at the foundation — regardless of which HubSpot integration path you end up building against.

Browse the Scalekit HubSpot connector → scalekit.com/agent-connector/hubspot