HubSpot Agent CLI vs MCP vs Custom API: Which Wins?

HubSpot now gives coding agents three paths into your CRM: the Agent CLI, the MCP server and a custom Claude Code skill. Here's which to pick, and when to stack them.

Key takeaways

• The HubSpot Agent CLI pairs a standalone hubspot binary with 18 pre-built skill files. It has been in public beta since June 2026 and is built for scheduled, bulk and background CRM work (HubSpot changelog, June 2026).
• The HubSpot MCP server provides typed, discoverable tools via per-user OAuth, giving you team permission enforcement without building auth infrastructure (HubSpot MCP Docs, 2026).
• Custom Claude Code skills open up delete operations, the full API surface and cross-system orchestration: the choice when your workflow doesn't fit a pre-built pattern.
• For most teams, the right answer is a hybrid: MCP server for daily CRM ops plus a lightweight custom skill for the edge cases. Agencies managing multiple clients should add the Agent CLI for standardised, repeatable client onboarding.

In 2026, HubSpot shipped not one but three distinct paths for connecting AI coding agents to your CRM. The Agent CLI (first offered as a private beta, public beta since 23 June 2026). The HubSpot MCP server (GA as of April 2026, at https://mcp.hubspot.com). And the existing REST API (date-versioned since 2026-03; the current version is 2026-09). Each path makes a different trade-off between setup speed, capability depth, and engineering control.

If you are a HubSpot partner, the question isn't academic. Pick the wrong path, and you're either over-engineering a simple client need or under-delivering on a complex one. So which trade-off matters most to your team: setup speed, capability depth, or per-user safety?

Quick comparison table

Who should choose what?

Sales and RevOps teams running standard HubSpot workflows: Start with the Agent CLI for the scheduled and bulk work. The pre-built skills cover pipeline management, deal tracking, ticket resolution, data quality, and sales reporting, exactly the work that consumes ops teams' time, with a five-minute setup. For interactive, day-to-day questions, add the MCP server alongside it.

Engineering teams building multi-system AI agents: Use the HubSpot MCP server. Its typed tool schemas and protocol-standard design mean you can swap LLM providers without rewriting anything. Connect alongside Slack's MCP server, Gmail's, and whatever else your agent touches. Reserve custom API skills for the operations that the MCP server doesn't support.

Teams with delete-heavy clean-ups or cross-system workflows: Build a custom Claude Code skill via the HubSpot API. You need delete operations, webhook-driven automation, or workflows that chain HubSpot to enrichment, then to Slack, then to email. The 30- to 60-minute setup is a one-time cost.

Agencies managing multiple client HubSpot instances: Install the Agent CLI for standardised per-client CRM operations. Supplement with a custom skill for cross-client reporting and agency-specific workflows that don't fit the pre-built patterns.

Teams with multiple Claude Code users who need per-user HubSpot permissions: Use the MCP server exclusively. Its per-user OAuth PKCE flow means your SDR can only see their owned deals, and your sales VP can view the full pipeline.

What are the three paths and how do they differ?

Each path operates at a different infrastructure layer: the Agent CLI runs locally, HubSpot hosts the MCP server, and custom skills use the REST API directly.

Path 1: HubSpot Agent CLI, the turnkey approach

The Agent CLI is a single hubspot binary with no runtime dependencies, plus a separate set of skill files that teach the agent how to plan its commands (HubSpot Agent CLI guide):

curl -fsSL https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.sh | sh
hubspot auth login
npx skills add hubspot/agent-cli-skills

The 18 skills in the Agent CLI Skills repo build on one foundation, bulk operations, and cover CRM lookup, deals, tickets, data quality, enrichment, quote-to-cash, workflow automation and custom object management, among others.

Every write command supports --dry-run, and some destructive commands, such as deletes and schema changes, require a local safety digest from a dry run before they execute. Audit goes through hubspot history, a local log of destructive operations.

HubSpot positions the Agent CLI for scheduled, bulk and background work, and the MCP server for interactive, human-in-the-loop tasks (HubSpot changelog, June 2026).

Path 2: HubSpot MCP server, the standard protocol

Launched as a public beta in September 2025 and GA since 13 April 2026 (HubSpot changelog), HubSpot's remote MCP server implements the Model Context Protocol to expose typed tools for CRM, campaign and content operations. Setup uses OAuth with PKCE, no API key to manage. You create an MCP connector in HubSpot (Development, then MCP Connectors), register http://localhost:8080/callback as its redirect URL, and pass its client ID to Claude Code (Claude Code MCP docs):

claude mcp add --transport http --scope user \
  --client-id <your-client-id> --client-secret --callback-port 8080 \
  hubspot https://mcp.hubspot.com

HubSpot's docs list more than 30 public tools, from search_crm_objects and manage_crm_objects to campaign, marketing email and content tools. Read and write access covers the core CRM objects, activities and custom object records; some tools depend on your subscription tier (HubSpot MCP Docs). Call get_user_details to see which tools your account can access.

The MCP server's key architectural advantage is that typed tool schemas sharply reduce the risk of AI hallucinations. Claude Code discovers property names at runtime rather than guessing from memory. That removes a common failure of raw API calls: writing to a field name that doesn't exist.

A limitation worth noting: if your HubSpot account has Sensitive Data enabled, activity and conversation data are blocked through the MCP server even though they remain accessible through the standard API.

Path 3: Custom Claude Code skill, full API control

Building a custom skill means wiring Claude Code directly to HubSpot's REST API. The simplest approach uses a service key, which HubSpot now recommends for in-account integrations: HubSpot blocked new legacy Private Apps from 26 October 2026 for existing accounts, though existing apps keep working (HubSpot changelog, August 2026).

curl -H "Authorization: Bearer $HUBSPOT_TOKEN" \
  https://api.hubapi.com/crm/objects/2026-09/contacts

You define every tool, every endpoint, every validation rule, across CRM, marketing, CMS and commerce (HubSpot API Reference).

The key advantage over both the Agent CLI and the MCP server: you're not limited to HubSpot.

How do they compare on setup, capability and safety?

Setup speed

The HubSpot Agent CLI wins on raw speed: one install, one login, one skills command, under 5 minutes.

The MCP server takes about 10 minutes for first-time setup: the connector, claude mcp add and the browser OAuth PKCE flow.

A custom skill takes 30 to 60 minutes. You're creating a service key, scoping permissions, writing tool definitions, handling pagination, and implementing retry logic. This is engineering work, not configuration.

Capability depth

Custom Claude Code skills win on raw capability: they expose the full API surface.

The MCP server's gaps are specific. There's no delete tool, and the search tool caps out at 5 filter groups with 6 filters each and 200 results per page, while a batch fetch takes up to 100 IDs. You can't export your full CRM through it. The Agent CLI streams JSONL and pages through large exports, but its schema and some delete operations need an admin service key.

A custom skill has none of these constraints. Delete? Available. Any API domain beyond CRM? All reachable. But here's the real question: does your team actually need all of that, or are you paying the engineering overhead for capabilities you won't use?

The rate limit reality: all three paths hit HubSpot's API limits. Privately distributed apps get 100 requests per 10 seconds on Free/Starter, 190/10s on Professional/Enterprise (250 with the API Limit Increase), while public OAuth apps get 110/10s per installing account (HubSpot API Usage Guidelines). A custom skill needs explicit retry logic that backs off on a 429 response, reads HubSpot's X-HubSpot-RateLimit-* headers and uses exponential backoff.

Safety and guardrails

The HubSpot Agent CLI wins on built-in safety: its dry-run and safety-digest pattern is purpose-built to prevent AI agents from destroying your CRM.

The MCP server is safe by design in a different way: typed tool schemas prevent hallucinated property names. But the MCP server doesn't enforce confirmation gates. If you ask Claude Code to update 200 contacts, the server won't stop to ask; any approval step lives in your client.

A custom skill has no built-in guardrails. Since API version 2026-09 (8 September 2026), HubSpot enforces admin-configured property validation rules on CRM API writes (HubSpot property validations guide), but those rules check format, not intent: a well-formed write to the wrong record still goes through. You must scope your service key narrowly, implement confirmation hooks in your skill, and never give the agent write access to objects it doesn't need. This is disciplined engineering, not a product feature. If you build it, put the gate in the tool, not in the prompt: here's how that gate works on a production CRM, with previews, typed record counts and undo.

Can it leave HubSpot, and who maintains it?

Cross-system workflows

Custom Claude Code skills win decisively: they're the only path that orchestrates across systems.

A real GTM automation might pull high-fit contacts from HubSpot, enrich via a data provider, check LinkedIn activity, draft outreach, create a deal in HubSpot, and notify Slack. The Agent CLI and the MCP server handle steps 1 and 5. Only a custom skill orchestrates the whole chain.

LLM portability

The MCP server wins on LLM portability: it's the only path that uses an open protocol, supported by Claude, Gemini, Codex, Cursor and other MCP-compatible clients. If you switch clients next year, your HubSpot connection follows you.

HubSpot builds the Agent CLI primarily for Claude Code, Claude Cowork and OpenAI Codex. Custom skills are markdown files wrapping curl commands, so any coding agent that can execute shell commands can use them, with minimal porting.

Maintenance burden

The MCP server and Agent CLI are tied for lowest maintenance. HubSpot owns the infrastructure. Custom skills are fully your responsibility.

The Agent CLI updates with hubspot upgrade and npx skills update. The risk: it's in beta, and HubSpot warns that commands, flags and behaviour may change without notice. The MCP server is GA server-side infrastructure: HubSpot adds tools and fixes bugs without you touching anything. The risk: if HubSpot adds new scopes, you need to reinstall the connector to grant them.

A custom skill is yours to keep alive. HubSpot's date-based API versioning (2026-03, 2026-09) means versioned endpoints eventually reach end of life. You track deprecations and schema drift yourself.

Who can do what when your whole team uses it?

The HubSpot MCP server wins on team permission enforcement: it's the only path where per-user permissions hold on every request without additional setup.

MCP server (per-user OAuth, zero additional work): Each user authenticates with their own HubSpot credentials via OAuth 2.1 with PKCE, and "all actions respect your existing HubSpot user permissions" (HubSpot MCP Docs). If a sales rep can only view their owned deals in HubSpot, that same restriction applies when they ask Claude Code to "show me my deals closing this week."

Agent CLI (per-user until someone needs admin mode): hubspot auth login scopes the token to the user's own HubSpot permissions. Schema operations and most deletes need a service key, which HubSpot warns "carries broader permissions and doesn't generate a per-user audit trail" (HubSpot changelog).

Custom skill with a shared service key (the default, simplest path): Its scopes are account-wide; it doesn't know which team member is making the request. HubSpot sets service key scopes per object type, such as crm.objects.contacts.read, on the key rather than on the person using it (HubSpot service keys docs).

Custom skill with per-user service keys (manual, but works for small teams): An admin issues each team member their own service key, scoped to their role, and each sets HUBSPOT_TOKEN to their personal key. The same skill file now respects per-role scopes, though scopes limit object types, not records: a rep's key still reads every deal, not just their own. Onboarding 20 team members means 20 keys, but for a team of 3-5 people, this is entirely workable.

In a Claude Team or Enterprise deployment, administrators can use managed settings to enforce which MCP servers are available (allowManagedMcpServersOnly), prevent users from adding their own permission rules (allowManagedPermissionRulesOnly), and block direct Bash HTTP calls (Bash(curl *) deny rules) (Claude Code managed MCP docs, Claude Code Permissions Docs). A deny rule doesn't catch /usr/bin/curl or sh -c 'curl ...', so pair it with the sandbox network allowlist. With these controls in place, the MCP server becomes the sanctioned path to HubSpot.

Frequently asked questions

Is the HubSpot Agent CLI ready for production?

Not yet. As of October 2026, it's in public beta, and HubSpot warns that write commands can change or remove live data. For production-critical workflows, the MCP server (GA since April 2026) or the direct REST API is a safer choice. Run --dry-run first and test in a sandbox account where you can.

What does each path cost?

All three paths are free at the tool level. The real cost is engineering time for setup and maintenance, plus Claude Code or LLM usage costs at runtime.

Verdict: category winners

The three paths aren't competing products; they're different points on a spectrum of control versus convenience. The MCP server sits in the middle: typed, discoverable, protocol-standard, and covering most of what teams actually need.

For most teams, the pragmatic path is to set up the MCP server first (10 minutes, GA, no regrets), install the Agent CLI alongside it if you want pre-built scheduled workflows, and build a lightweight custom skill for the operations that neither covers.