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

Key Takeaways

• The HubSpot Agent CLI ships 15 pre-built skill files in under 5 minutes, ideal for standard CRM workflows with zero engineering overhead.

• The HubSpot MCP server provides 12 typed, discoverable tools via per-user OAuth, giving you team permission enforcement without building auth infrastructure (HubSpot MCP Docs, 2026).

• Custom Claude Code skills unlock custom objects, delete operations, 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 20% of edge cases. If you are managing multiple hubspot portals then add the Agent CLI for standardized, repeatable client onboarding.

Introduction

In early 2026, HubSpot shipped not one but three distinct paths for connecting AI coding agents to your CRM. The Agent CLI (May 2026, 15 markdown skill files). The HubSpot MCP server (GA as of April 2026, at https://mcp.hubspot.com). And the existing REST API (now date-versioned as 2026-03), usable from any custom Claude Code skill. (New to building custom skills? See our Claude Code custom skills guide for the step-by-step.) Each path makes a different trade-off between setup speed, capability depth, and engineering control.

If you run a HubSpot agency, 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. Pick the right combination, and your team moves faster than competitors who are still clicking through the HubSpot UI.

HubSpot's internal engineering team has already validated this architecture at scale. Their platform, called Crucible, powered over 7,000 fully AI-generated pull requests and 50,000 AI-reviewed PRs in six months using Claude Code running on Kubernetes (Cloud Coding Agents at HubSpot, January 2026). That internal dogfooding shaped the Agent CLI's safety patterns (dry-run/digest/confirm) and informed the MCP server's typed tool schema design.

Watch the HubSpot MCP Server demo on YouTube.

HubSpot Developers demonstrate the MCP server scaffolding projects from plain-language descriptions in under 15 minutes.

Quick Comparison Table

Who Should Choose What

If you only read one section, make it this one.

Sales and RevOps teams running standard HubSpot workflows: Start with the Agent CLI. The 15 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. If you hit a limitation (custom objects, cross-system needs), add the MCP server as a supplement.

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 heavy custom objects or cross-system workflows: Build a custom Claude Code skill via the HubSpot API. You need custom objects, delete operations, webhook-driven automation, or workflows that chain HubSpot to enrichment, then to Slack, then to email. The 30–60 minute setup is a one-time cost.

For HubSpot Solutions Partners managing multiple client HubSpot instances: Install the Agent CLI to standardize per-client CRM operations. It's fast, safe, and consistent across clients - every engagement starts from the same 15-skill baseline. Supplement with a custom skill for cross-client reporting, custom object access, and agency-specific workflows that don't fit the pre-built patterns. For more on automating multi-client RevOps, see our AI agent orchestration guide. For per-client permission enforcement, the MCP server is the right call, but it requires individual OAuth setup per client instance, which adds onboarding friction for high-volume agencies.

Teams with multiple Claude Code users who need per-user HubSpot permissions: Use the MCP server exclusively. This is non-negotiable. The MCP server's per-user OAuth PKCE flow means your SDR can only see their owned deals, your marketing manager has read-only CRM access, and your sales VP can view the full pipeline. Combine with Claude Code for Teams managed settings (allowManagedMcpServersOnly, deny "Bash(curl *)") to enforce that the MCP server is the only path to HubSpot data.

If none of these fit, HubSpot's native Workflows or Zapier handle simpler triggers without an AI agent. Reserve Claude Code integration for tasks that need reasoning: data classification, enrichment decisions, or multi-step conditional logic that a rules engine can't express.

For HubSpot Solutions Partners: The fastest path to standardize across clients is the Agent CLI. One npx skills command per client engagement. Same 15 skills. Same safety patterns. Same training. When a client needs custom objects or cross-system workflows, add a lightweight custom skill. When they need per-user permissions (enterprise clients, compliance requirements), switch to the MCP server. The three paths stack - they don't compete.

What Are the Three Paths and How Do They Differ?

Each path gives Claude Code (or any AI agent) access to HubSpot CRM data. The difference is how much HubSpot manages for you versus how much you control yourself.

Path 1: HubSpot Agent CLI - The Turnkey Approach

This isn't a standalone binary. It's 15 markdown skill files installed via npm that teach AI agents how to use the hubspot CLI:

npx skills hubspot/agent-cli-skills

The 15 skills cover: bulk operations (the foundation), CRM-lookup, deal-management, sales-execution, sales-reporting, ticket-resolution, audience-targeting, CRM-data-quality, customer-retention, data-enrichment, quote-to-cash, workflow-automation, team-ownership, communication-history, and custom-object-management.

Every skill inherits from bulk-operations, which enforces a three-phase safety gate for destructive operations: dry-run (preview), digest (review impact), confirm (explicit approval). Recovery is handled via hubspot history.

The Agent CLI is designed for autonomous, scheduled work - Monday morning pipeline reports, inactive-contact cleanup scans, and pre-call research briefs. It's the "set it and forget it" option.

Path 2: HubSpot MCP Server - The Standard Protocol

Launched as a public beta in January 2026 and GA since April, HubSpot's remote MCP server (https://mcp.hubspot.com) implements Anthropic's Model Context Protocol to expose 12 typed tools. (Not familiar with MCP? Read our Model Context Protocol overview.) Setup uses OAuth 2.1 with PKCE - no API key to manage:

claude mcp add --transport http --scope user hubspot https://mcp.hubspot.com

After authenticating inside Claude Code (browser OAuth flow), you get these tools:

Read access covers contacts, companies, deals, tickets, products, quotes, invoices, subscriptions, segments, and activities (calls, emails, meetings, notes, tasks), as well as content objects (blog posts, landing pages, campaigns). Write access covers contacts, companies, deals, tickets, line items, products, and activities.

The MCP server's key architectural advantage is that typed tool schemas prevent AI hallucinations. Claude Code can't invent property names - it discovers them via find_property_definitions and get_property_detail. This eliminates the most common failure mode of raw API calls, where the model guesses field names and writes to non-existent properties.

A limitation worth noting: if your HubSpot account has Sensitive Data enabled, activity objects (calls, emails, meetings, notes, tasks) 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 Private App token:

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

You define every tool, every endpoint, every validation rule. HubSpot's API covers CRM objects (contacts, companies, deals, tickets, products, line items, quotes, custom objects), marketing (emails, forms, lists), CMS (pages, blogs, themes, HubDB), commerce (invoices, payments, subscriptions), and the new Agent Tools API (beta) for building agent extensions directly on HubSpot's platform (HubSpot API Reference).

Here's what a minimal custom skill tool definition looks like in practice:

## search_contacts

Search HubSpot contacts by property value. Returns up to 100 results.

**Parameters:**
- `property` (string, required): HubSpot property internal name (e.g., "email", "company")
- `value` (string, required): Value to search for
- `limit` (number, optional): Max results (default 50, max 100)

**Usage:**
curl -H "Authorization: Bearer $HUBSPOT_TOKEN" \
  "https://api.hubapi.com/crm/v3/objects/contacts/search" \
  -d '{"filterGroups":[{"filters":[{"propertyName":"'$property'","operator":"EQ","value":"'$value'"}]}],"limit":'$limit'}'

The key advantage over both the Agent CLI and the MCP server: you're not limited to HubSpot. A custom skill can pull HubSpot contacts, enrich them via Clearbit or Apollo, check LinkedIn activity, draft outreach, create a deal, and notify Slack - all in one Claude Code session. Neither the Agent CLI nor the MCP server can cross system boundaries.

Watch how outbound campaigns run from Claude Code on YouTube

Ben Holley (AirOps) demonstrates how to run entire outbound campaigns from Claude Code, wiring 10+ APIs, including HubSpot, into a single terminal workflow.

For HubSpot Solutions Partners: A custom skill is your differentiator. Build it once for a common client need (say, "segment contacts by last engagement date and create a re-engagement list"), and you can deploy it across every client that fits the pattern. The 30–60 minute initial build pays for itself on the second deployment.

What Each Path Can (and Can't) Do - Full Capability Matrix

Before diving into the comparison categories, here's the definitive list of operations each path supports. If you're trying to decide between paths, start here.

CRM Objects

Activities and Engagement

Marketing and Campaigns

Automation and Workflows

Advanced Operations

Key Limitations to Watch For

• Agent CLI: No deletes ever. No custom object records. No marketing campaigns. Workflow management is CLI-template-based, not programmable. The hubspot CLI auth is a shared credential - every team member gets the same CRM access regardless of their HubSpot role.

• MCP Server: No deletes. No custom objects. No workflows. No forms. Engagement data is blocked if Sensitive Data is on. Search capped at 10,000 results. Community users have flagged the 10-record connector limit as trivially bypassed via Claude loops - a data integrity concern for admins (HubSpot Community: Connector Permissioning Needs, May 2026).

• Custom API Skill: No pre-built guardrails. You handle pagination, rate limits, retries, schema drift, and API version migrations yourself. The Search API uses a 10,000-result hard limit - use getPage the basic API for full exports instead. Full flexibility means full responsibility.

Advanced Operations: Workflows, Pagination, and Blueprints

Some of the most powerful CRM automation patterns are only possible with direct API access. Here's what that looks like in practice.

Technical Deep Dive: The next three sections cover pagination mechanics, workflow automation via API, and reusable blueprints. If you're evaluating capabilities at a high level, skip to Category 1: Setup Speed. If you're the technical lead who's been forwarded this post, this is where the detail lives.

Building Automated Workflows via the API

HubSpot's Workflows v4 API (/automation/v4/flows) lets you programmatically create, update, and delete workflows with enrollment triggers, conditional branching, delays, and CRM actions. This is available only through the custom API skill path.

The MCP server has no workflow tools. The Agent CLI has workflow-automation skills, but they're CLI-template-based - you can create a workflow from a template. Still, you can't programmatically define custom enrollment criteria, chain multi-step actions, or enroll records programmatically.

With the API, a Claude Code skill can dynamically build workflows. Example prompts:

• "Create a workflow that enrolls contacts when they submit the demo request form, waits 2 hours, creates a follow-up task for the assigned owner, and adds the contact to the 'New Leads' list."

• "Find all inactive workflows for deals that haven't been modified in 90 days and disable them."

The Workflows v4 API requires the automation scope and is currently in beta. Combined with the CRM API, it turns Claude Code into a workflow automation engine: define the logic in natural language, and the skill translates it into API calls.

Here's what a workflow creation call looks like through a custom skill:

curl -X POST -H "Authorization: Bearer $HUBSPOT_TOKEN" \
  "https://api.hubapi.com/automation/v4/flows" \
  -d '{
    "name": "Demo Request Follow-up",
    "type": "CONTACT",
    "enrollmentCriteria": {
      "type": "FORM_SUBMISSION",
      "formId": "12345"
    }
  }'

How Pagination Works Across the Three Paths

Pagination is where the paths diverge sharply. These limits matter once your CRM grows beyond a few thousand records.

Agent CLI: Uses JSONL pipes for data transfer. The bulk-operations foundation skill handles pagination transparently - hubspot CLI commands stream results to stdout in JSONL format, and the skill files teach Claude Code to parse, filter, and batch them. Pagination is unlimited. If you have 100,000 contacts, the Agent CLI streams them all.

MCP Server: Uses the CRM Search API under the hood. The search_crm_records tool supports up to 5 filter groups with 6 filters each, returns a maximum of 200 results per page, and caps at 10,000 total results (Search API limit). The get_crm_records_by_ids tool fetches up to 100 objects per call. For most operational workflows, these limits are fine. But you can't export your full CRM via the MCP server.

Custom API Skill: You have full control and two pagination strategies:

1. getPage pagination (recommended for exports): Uses the basic API (/crm/v3/objects/{type}) with cursor-based pagination via paging.next.after. No record count limit - you can export your entire CRM. The established pattern is an async generator that yields records as they arrive, with checkpoint persistence for resumability across Claude Code sessions.

2. Search API with watermark sliding: For incremental syncs, use the Search API filtered by lastmodifieddate. When you hit the 10K limit, slide the watermark window forward. Combine getPage for the initial full export.

For batch writes, all three paths share HubSpot's batch endpoint limit of 100 records per call. A custom skill typically implements a chunking helper that splits large arrays into 100-record groups with exponential backoff for 429 Rate Limit responses, retrying up to 3 times before surfacing errors.

The Blueprint Pattern for Complex Operations

A custom API skill can implement reusable blueprints - pre-defined multi-step operation templates that Claude Code invokes as a single command. This is powerful for repetitive, complex CRM tasks that the Agent CLI and MCP server can't express.

Segmentation blueprint example:

Blueprint: "segment-contacts"
Input: list_id, segment_criteria, target_list_name
Steps:
1. GET /crm/v3/lists/{list_id}/memberships - fetch all members (paginated via getPage)
2. Filter results by segment_criteria (property values, activity recency, deal status)
3. POST /crm/v3/lists - create target list
4. POST /crm/v3/lists/{target_id}/memberships/add - add filtered contacts (100/batch)
5. Return: segment count, target list ID, summary

A Claude Code user says: "Split my high-value contacts list into three segments: engaged in last 30 days, not engaged in 30-90 days, and lost (>90 days)." The blueprint handles pagination, batch API calls, list creation, and returns a summary - all in one invocation.

Neither the Agent CLI nor the MCP server can build blueprints. The Agent CLI's skills are static markdown files - they teach Claude Code how to use the CLI, but they can't define reusable multi-step operations with conditional logic. The MCP server's tools are atomic (one tool = one API call). Blueprints are a custom skill superpower: they encode institutional knowledge about how your team builds CRM automations, making Claude Code more reliable and faster for repeated operations.

Category 1: Setup Speed - Which Takes the Least Time?

The HubSpot Agent CLI wins on raw speed - one npm command, under 5 minutes. But the MCP server is close behind and delivers far more architectural flexibility.

The Agent CLI npx skills hubspot/agent-cli-skills is genuinely frictionless. It drops markdown files into .claude/skills/ and references your existing. hubspot CLI authentication. No OAuth flows, no environment variables, no tool definitions to write.

The MCP server takes about 10 minutes for first-time setup. You create an MCP auth app in HubSpot, runclaude mcp add, and complete the browser OAuth PKCE flow. After that initial setup, it's available across all Claude Code sessions with automatic token refresh. In our experience, most of those 10 minutes are spent finding the right HubSpot settings page, not on technical complexity.

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

Where the MCP server pulls ahead of the Agent CLI: once set up, your tools are typed and discoverable. Claude Code can inspect property schemas at runtime and adapt to your CRM's actual field layout. The Agent CLI's skills assume a standard HubSpot schema; if your portal has heavy custom property usage, the MCP server adapts better.

Bottom line: Agent CLI for instant-start CRM ops. MCP server for the best balance of speed and future-proofing. Custom skills when neither pre-built option reaches far enough.

Category 2: Capability Depth - What Can You Actually Do?

Custom Claude Code skills win on raw capability - they expose the full API surface. The MCP server covers roughly 80% of real-world CRM needs. The Agent CLI covers roughly 60% of the functionality and focuses on sales and service workflows.

A 2026 analysis by SyncGTM found that 80% of HubSpot CRM operations map to the MCP server's 12 tools, with custom objects, deletes, and marketing API access driving the remaining 20% (SyncGTM, 2026). This split means most teams can start with the MCP server and add custom skills only for the operations that genuinely need them.

The Agent CLI's 15 skills are opinionated. They cover pipeline management, deal tracking, ticket resolution, data quality, sales reporting, and workflow automation well. But there are hard gaps: no delete operations, a 10-record bulk cap, and custom object schema management without access to custom object records. The bulk-operations skill works around the record limit with JSONL pipes, but you're still inside the connector's guardrails.

The MCP server is broader. It covers the full CRM object graph (contacts, companies, deals, tickets, products, quotes, invoices, subscriptions) plus campaign analytics - something the Agent CLI doesn't support. Its search_crm_records tool supports complex filter groups (5 groups × 6 filters each, AND within groups, OR across them) with 200 results per page. But it also has gaps: no delete tool, no custom object endpoint, no bulk write operations.

A custom skill has none of these constraints. Custom objects? Full CRUD via /crm/objects/2026-03/{objectType}. Bulk operations? Batch endpoints handle up to 100 records per call. Delete? Available. Any API domain beyond CRM (marketing analytics, CMS content, commerce transactions)? All reachable.

The rate limit reality: all three paths hit the same HubSpot ceiling - 100 requests per 10 seconds for private apps, 200/10s for OAuth. The Agent CLI and the MCP server handle the 429 Retry-After response internally. A custom skill needs explicit retry logic with exponential backoff.

Takeaway: MCP server for 80% of CRM operations with type safety. Custom skills when you need the other 20% - custom objects, deletes, or non-CRM API domains. Agent CLI for sales/service workflows within its scope.

For HubSpot Solutions Partners: The capability gap between MCP server and custom skill is where agency value lives. If a client needs a custom object for "installations" or "warranty claims," only the custom skill path works. Build it once. Deploy it across every client with that object. The MCP server handles the boring 80% of CRM work across all clients simultaneously.

Category 3: Safety and Guardrails - Which Protect Your CRM Data?

The HubSpot Agent CLI wins on built-in safety - its dry-run/digest/confirm pattern is purpose-built to prevent AI agents from destroying your CRM. The MCP server is safer than a raw custom skill but less opinionated than the Agent CLI.

The Agent CLI's bulk-operations The foundation enforces a three-phase safety gate: dry-run (preview every change), digest (review the impact summary), and confirm (explicit approval required). Combined with hubspot history rollback, this creates a safety net that's genuinely hard to replicate. HubSpot's internal Crucible platform adds Claude Code hooks that block bad commit messages and enforce coding standards - the Agent CLI inherits this defensive DNA.

The MCP server is safe by design in a different way: typed tool schemas prevent hallucinated property names. Claude Code can't write to a field that doesn't exist because it discovers fields through find_property_definitions. But the MCP server doesn't enforce confirmation gates. If you ask Claude Code to update 200 contacts, it can do so in a single create_or_update_crm_records call. The safety comes from schema validation, not from workflow gates.

A custom skill has no built-in guardrails. HubSpot's UI validation rules don't apply through the API - a malformed email will be accepted. You must scope your Private App narrowly, implement confirmation hooks in your Claude Code skill file, and never give the agent write access to objects it doesn't need. This is disciplined engineering, not a product feature.

Recommendation: Agent CLI for teams that need opinionated safety gates. MCP server for schema-level safety without workflow friction. Custom skills: add your own guards or accept the risk.

Category 4: Cross-System Workflows - Can It Leave HubSpot?

Custom Claude Code skills win decisively - they're the only path that orchestrates across systems. The Agent CLI and MCP server are both HubSpot-only by design.

The 2026 MCP vs Direct APIs architectural decision matrix found that protocol-standard servers like HubSpot's MCP excel at single-system reliability, but cross-system workflows require direct API integration where no single protocol governs the full chain (AgentMarketCap, April 2026). This is the architectural reality behind custom skills: MCP standardizes individual connections, but orchestration still occurs at the agent level.

Here's the architectural split. The Agent CLI and MCP server run entirely within HubSpot's ecosystem: read CRM, write CRM, report on CRM. For pure CRM automation, that's exactly right. But modern RevOps workflows rarely stay within a single system.

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

The MCP server does have an advantage the Agent CLI lacks: it's protocol-standard, so the same Claude Code session can connect to multiple MCP servers simultaneously (HubSpot + Slack + Gmail + a web search tool). But the orchestration still occurs at the agent level - the MCP servers don't communicate with each other. A custom skill can implement cross-system logic in its tool definitions.

Bottom line: Custom skills for any workflow spanning HubSpot + external systems. MCP server for multi-tool agents, where HubSpot is one of several connected services. Agent CLI for CRM-only automations.

Category 5: LLM Portability - Which Works If You Switch Models?

The MCP server wins on LLM portability - it's the only path that uses an open protocol. The Agent CLI is tied to specific coding agents. Custom skills are Claude Code-specific.

The MCP server implements Anthropic's Model Context Protocol, an open standard now supported by Claude, GPT-5, Gemini, Codex, and Cursor. If you switch from Claude Code to another MCP-compatible client next year, your HubSpot MCP server connection follows you. Tool schemas are client-agnostic.

The Agent CLI's skill files are markdown documents consumed by Claude Code, Codex, and Cursor. They work across the supported agents but aren't protocol-standard; each agent interprets the markdown instructions differently. If a new agent enters the market, HubSpot needs to add explicit support.

Custom Claude Code skills are hard-tied to Claude Code's tool definition format. Porting to another agent means rewriting tool schemas in that agent's format or building an MCP server wrapper around your custom logic - which brings you back to the MCP path anyway.

Takeaway: Use an MCP server for future-proof LLM flexibility. Agent CLI if you're committed to the supported agent ecosystem. Custom skills if Claude Code is your permanent platform.

Category 6: Maintenance Burden - Who Fixes It When It Breaks?

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 npm update When HubSpot ships new skill versions. HubSpot maintains API compatibility, adds new skills, and fixes bugs. The risk: it's in private beta, so HubSpot hasn't committed to a GA timeline or published a maintenance SLA.

The MCP server is GA and is a server-side infrastructure. HubSpot can add tools (get_campaign_analytics didn't exist at launch), update schemas, and fix bugs without you having to touch anything. When they deprecate an API version, the MCP server handles the migration internally. The risk: if HubSpot adds new scopes, you need to re-authenticate to grant them.

A custom skill is your full responsibility. HubSpot's date-based API versioning (2026-03) means versioned endpoints eventually reach the end of life. You track deprecation timelines, migrate tool definitions, and handle schema drift when HubSpot adds or renames properties. Community MCP servers like mcp-hubspot (npm) Split the difference - the maintainer handles API changes, but you're dependent on an open-source project's release cadence.

Recommendation: MCP server for the lowest maintenance with the broadest feature set. Agent CLI once it reaches GA. Custom skills are only used when the capabilities justify the maintenance overhead.

Category 7: Team Permission Management - Who Can Do What?

The HubSpot MCP server wins on team permission enforcement - it's the only path where per-user OAuth works without additional setup. But the story for custom skills isn't as binary as most comparisons suggest. There are four approaches, each with different trade-offs.

The Fundamental Problem

When you connect Claude Code to HubSpot, who does HubSpot think is making the request? The answer determines whether your SDR can accidentally (or intentionally) modify deals they shouldn't touch.

How Each Path Handles Identity

1. Agent CLI (shared credential, no per-user boundary): The Agent CLI uses your existing hubspot CLI authentication is tied to a single HubSpot user account. Every team member who runs npx skills hubspot/agent-cli-skills in their Claude Code session uses the same underlying CLI auth. If that auth belongs to a Super Admin, every Claude Code session on every team member's machine has Super Admin-level CRM access. There is no per-user permission boundary.

2. Custom skill with a shared Private App token (the default, simplest path): A Private App token is tied to the user who created it and breaks if that user leaves. Its scopes are account-wide - it doesn't know which team member is making the request. HubSpot's own documentation confirms that OAuth and Private App tokens "do not reflect the permissions or limitations of what a user can do in their HubSpot account" (HubSpot OAuth FAQ). A token with a contact read scope can read all contacts, not just the ones the requesting user owns.

3. Custom skill with per-user Private Apps (manual, but works for small teams): Each team member creates their own Private App in HubSpot, scoped to their own permissions. They set HUBSPOT_TOKEN their personal token. The same custom skill file now respects per-user permissions because each token has different scopes tied to its creator. This is per-user auth without any OAuth infrastructure. The downsides are real: everyone needs to navigate HubSpot's app creation UI, tokens break when people leave, and onboarding 20 team members means 20 Private App setups. But for a team of 3-5 people, this is entirely workable.

For HubSpot Solutions Partners:The per-user Private App approach is the practical option for small agency teams. Three developers, three Private Apps, three personal tokens. When someone leaves, revoke their token. When someone joins, they create one. It's not elegant, but it works without adding a vendor dependency.

4. Custom skill with hand-rolled OAuth (major engineering lift): You can build a token management layer into your custom skill - something that launches a browser OAuth flow, stores and refreshes tokens per user, and injects the right token into each request. This is exactly what the MCP server does for free. The LLM interprets Claude Code skills at runtime; it doesn't have a persistent runtime to manage OAuth state across sessions. Building this yourself means managing OAuth 2.1 with PKCE, token refresh logic, secure credential storage, and session management. It's possible. It's also reinventing a wheel that the MCP server already ships.

5. MCP server (per-user OAuth, zero additional work): Each user authenticates individually with their own HubSpot credentials via OAuth 2.1 with PKCE. The resulting access token is scoped to that specific user. If a sales rep only has permission to view their owned deals in HubSpot, that same restriction applies when they ask Claude Code to "show me my deals closing this week." A marketing manager with read-only CRM access can query contacts but can't modify them.

The Claude Code for Teams Angle

This distinction becomes critical in a Claude Code deployment for Teams or Enterprise. (See our Claude Code for Teams setup guide for the full configuration walkthrough.) Administrators can use managed settings to enforce which MCP servers are available (allowManagedMcpServersOnly), prevent users from adding custom API tools (allowManagedPermissionRulesOnly), and block direct Bash HTTP calls (Bash(curl *) deny rules) (Claude Code Permissions Docs). With these controls in place, the only path to HubSpot is through the MCP server, which enforces per-user HubSpot permissions.

The Claude.ai Shared Token Problem

If you're using Claude.ai's organization-level MCP connectors (rather than the Claude Code CLI), there's a known limitation. As of mid-2026, organization connectors use a single shared OAuth token for all members; whoever authenticates last sets the token for the entire org. This means the per-user permission model only works reliably when team members connect to the MCP server individually via the Claude Code CLI, not through a centrally managed org connector.

Practical Setup for Teams

For a team of 10 using Claude Code with HubSpot, here's what each approach looks like in practice:

MCP server path:

1. Admin setup (once): Create an MCP auth app in HubSpot. Add the MCP server to the managed MCP server allowlist.

2. Each team member (once): Run claude mcp add --transport http --scope user hubspot https://mcp.hubspot.com. Complete the browser OAuth flow with their own HubSpot credentials.

3. Ongoing: Each session automatically uses that individual's OAuth token. HubSpot enforces existing user permissions.

Per-user Private App path (custom skill):

1. Each team member (once): Create a Private App in HubSpot with scopes matching their role. Set HUBSPOT_TOKEN in their environment.

2. Ongoing: Same skill file, different tokens, per-user permissions enforced by token scope.

3. Maintenance: Revoke tokens when people leave. New hires create their own Private App.

Bottom line: MCP server is the lowest-friction path to per-user permissions. For small teams (under 5), per-user Private Apps with a custom skill are a workable alternative with no vendor dependency. The Agent CLI and a shared Private App token both bypass per-user access controls entirely.

What Are the Pros and Cons of Each Path?

HubSpot Agent CLI

Best when: You're a sales/RevOps team or agency that wants CRM automation without writing code. Your workflows fit standard CRM patterns. Zero maintenance matters more than unlimited flexibility.

HubSpot MCP Server

Best when: You're building multi-system AI agents and want HubSpot as one connected service among many. You value type safety and discoverable schemas. Per-user permissions matter to your compliance requirements.

Custom Claude Code Skill (HubSpot API)

Best when: You need custom objects, deletes, non-CRM API domains, or workflows spanning multiple systems. You have engineering resources to build and maintain tool definitions. Full control matters more than setup speed.

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. For a team with a dedicated RevOps engineer, the custom skill's flexibility pays for itself. For a sales team or agency without engineering support, the MCP server offers 80% of the capability with 20% of the setup effort.

How to Get Started (Copyable Commands)

Agent CLI - 5 minutes

# Install the 15 skill files
npx skills hubspot/agent-cli-skills

# Verify installation
ls .claude/skills/hubspot-*

# Run your first CRM query
# "Show me all deals closing this month"

MCP Server - 10 minutes

# 1. Create an MCP auth app in HubSpot (Settings > Integrations > MCP Apps)
# 2. Add the server to Claude Code
claude mcp add --transport http --scope user hubspot https://mcp.hubspot.com

# 3. Complete the browser OAuth flow
# 4. Verify: ask Claude Code "Search my HubSpot contacts for any company in California"

Custom API Skill - 30-60 minutes

# 1. Create a Private App in HubSpot (Settings > Integrations > Private Apps)
# 2. Scopes needed at minimum: crm.objects.contacts.read, crm.objects.contacts.write
# 3. Set your token
export HUBSPOT_TOKEN="your-token-here"

# 4. Create a skill file at .claude/skills/hubspot-custom.md
# 5. Define your tools (see Path 3 section above for template)
# 6. Test: "Search contacts where email contains @example.com"

Frequently Asked Questions

Which HubSpot integration path should I start with?

Start with the MCP server. It's GA, sits in the middle ground, and offers typed tool schemas that prevent the most common failure mode (hallucinated property names). The 10-minute setup via claude mcp add It is a one-time cost — see our HubSpot MCP server setup walkthrough for the step-by-step. If you hit the MCP server's limitations (no custom objects, no deletes, no cross-system workflows), add a custom skill for those operations. If you find yourself doing mostly standard CRM tasks, install the Agent CLI alongside it - the two coexist without conflict since Agent CLI skills are just markdown files in .claude/skills/.

Can I use all three paths together?

Yes, and many teams should. The MCP server gives you typed, discoverable CRM access for daily operations. The Agent CLI handles scheduled, autonomous tasks, such as weekly pipeline reports, through its dry-run/digest/confirm safety pattern. A custom skill handles the edge cases that neither covers: custom objects with full CRUD, cross-system enrichment pipelines, delete operations, and webhook-driven automation. The three paths don't conflict because they operate at different levels of abstraction.

Does the MCP server replace the need for HubSpot API knowledge?

For roughly 80% of CRM operations, yes. According to HubSpot's own documentation, typed tools like search_crm_records and create_or_update_crm_records abstract the API behind discoverable schemas (HubSpot MCP Tools Reference, 2026). For the 20% of cases, the MCP server doesn't cover - custom objects, deletes, webhook-driven workflows, non-CRM API domains - you still need API knowledge to build a custom skill. But the MCP server meaningfully reduces the surface area you need to learn.

Is the HubSpot Agent CLI ready for production?

Not yet. As of June 2026, it's in private beta with no announced GA date. The skill files are open source under the Apache 2.0 license, and you can install and use them today. Still, HubSpot doesn't guarantee API compatibility or provide support. For production-critical workflows, the MCP server (GA since April 2026) or the direct REST API (stable, date-versioned) is a safer choice. Install the Agent CLI alongside them for experimental or non-critical automation.

How do rate limits compare across the three paths?

All three hit the same HubSpot API rate limits: 100 requests per 10 seconds for private apps, 200 requests per 10 seconds for OAuth (HubSpot API Usage Guidelines). The MCP server and Agent CLI handle 429 Retry-After responses internally. With a custom skill, you implement retry logic yourself. The MCP server adds server-side caps on top: 200 results per search page, 100 object IDs per batch fetch, 5 filter groups with 6 filters each.

What happens to my integration when HubSpot changes its API?

HubSpot moved to date-based API versioning (e.g., /crm/objects/2026-03/contacts) in early 2026 (HubSpot API Versioning Overview). The MCP server and Agent CLI handle version migrations internally - HubSpot updates the server or skill files. A custom skill requires you to track deprecation timelines yourself. Budget roughly 2 hours per quarter to audit your custom skill's API compatibility.

How do team permissions work when multiple people use Claude Code with HubSpot?

There are four approaches, not one. The MCP server gives per-user OAuth for free — each person authenticates with their own HubSpot login, permissions enforced automatically. The Agent CLI uses shared CLI auth — everyone gets the same access. A custom skill with a shared Private App token acts as a service account. Per-user Private Apps work for small teams — manual but functional, no vendor dependency. Hand-rolling OAuth duplicates what the MCP server already does. For teams larger than 5, the MCP server is the clear winner.

Can Merge.dev enforce per-user authentication with the Agent CLI or HubSpot API?

With the HubSpot API, yes — Merge effectively fixes the per-user auth gap. With the Agent CLI, no — Merge replaces it; it doesn't augment it.

Merge's Agent Handler uses a Registered User model in which each team member has their own MCP endpoint and OAuth connection. HubSpot enforces that an individual user's permissions on every request (Merge Access Control Lists docs). This means you get per-user auth, 70+ typed CRM tools (broader than HubSpot's 12 native tools), plus enterprise features like DLP scanning and full audit trails — all without building OAuth infrastructure yourself.

The Agent CLI can't integrate with Merge because it uses the hubspot CLI's own shared credential. Merge wraps the HubSpot API, not the CLI.

The trade-off: Merge is a paid third-party dependency with rate limits (600 GET/min, 120 writes/min per org). And you're adding another vendor between Claude Code and HubSpot. But for teams that need per-user auth, audit trails, and DLP scanning alongside broad CRM tool coverage, it's the most complete option beyond HubSpot's native MCP server (Merge Agent Handler Overview).

Verdict: Category Winners

The three paths aren't competing products - they're different points on a spectrum of control versus convenience. The Agent CLI gives you the most convenience with the least flexibility. The custom API skill gives you the most flexibility with the most engineering overhead. The MCP server sits in the middle: typed, discoverable, protocol-standard, and covering 80% of what most teams actually need.

For most teams in 2026, 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 autonomous workflows, and build a lightweight custom skill for the operations neither covers. That gives you the best of all three worlds without over-engineering the solution.

Sources: HubSpot Agent CLI Skills Repository, HubSpot API Reference, Introducing the HubSpot Agent CLI (HubSpot Blog), Integrate AI Tools with the HubSpot MCP Server (HubSpot Docs), HubSpot MCP Server Tools Reference, Developer MCP Server Tools Reference, Claude Code HubSpot Integration Guide (SyncGTM), Cloud Coding Agents at HubSpot, MCP vs Direct APIs: 2026 Decision Matrix