How to Connect Your Agents to HubSpot MCP via Claude Code

This guide walks you through connecting AI agents to Merge Agent Handler's HubSpot MCP server with Claude Code.

By the end, you'll have a working MCP configuration that gives your Claude agents direct access to HubSpot's CRM, enabling them to read and update contacts, manage deals, log activities, and more without leaving your terminal.

Prerequisites

Before getting started, you'll need:

• A Merge Agent Handler account

• Claude Code installed and configured

• HubSpot account with admin or API access

• A Tool Pack in Merge Agent Handler with the HubSpot connector enabled

• A Registered User in Merge Agent Handler (generates the MCP URL)

• An API key from Merge Agent Handler

Related: A guide to connecting to the Zendesk MCP with Claude Code

How it works

Merge Agent Handler sits between your AI agent and HubSpot's API.

You define a Tool Pack, a bundle of connectors and scoped permissions, and a Registered User, the identity context under which the agent operates. Together, these produce a unique MCP URL that your agent uses to call HubSpot tools securely.

Claude Code connects to that MCP URL over HTTP, making HubSpot's tools available as native functions inside any Claude session. You never expose raw HubSpot credentials to the agent; Merge handles authentication and enforces the tool-level permissions you've configured.

Setup steps

Here's what you'll need to do:

1. Create a Tool Pack

Log into the Merge Agent Handler dashboard and navigate to Tool Packs, and then select Create Tool Pack.

Give your Tool Pack a name (e.g., "Sales Agent – HubSpot"), then find and enable the HubSpot connector. You can scope which HubSpot tools the agent can access. For example, limiting it to read-only contact data or granting full CRM write access depending on your use case.

2. Add a Registered User

Inside your Tool Pack, go to Registered Users, and then select Add Registered User. You'll then see the following UI:

This creates an identity record representing the agent's operational context (e.g., a specific sales rep, a team inbox, or a generic automation user). From there, Merge generates a unique MCP URL tied to that Registered User.

3. Gather your credentials

From the Merge Agent Handler dashboard, collect the following:

• Tool Pack ID: found in the Tool Pack's settings page

• Registered User ID: found under the Registered User's detail view

• API Key: generate one under Settings, and then API Keys.

Your MCP URL will follow this format:

https://ah-api.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp

4. Configure Claude Code

Run the following command in your terminal, substituting your actual values

claude mcp add --transport http agent-handler \
  "https://ah-api.merge.dev/api/v1/tool-packs/YOUR_TOOL_PACK_ID/registered-users/YOUR_REGISTERED_USER_ID/mcp" \
  --header "Authorization: Bearer YOUR_API_KEY"

5: Verify the connection

Confirm the server is registered and healthy:

claude mcp list

You should see <code class="blog_inline-code">agent-handler</code>listed with a <code class="blog_inline-code">✓ Connected</code> status.

Now open a Claude Code session.

Ask Claude to list available HubSpot tools. It should enumerate contacts, deals, companies, and activity endpoints.

{{this-blog-only-cta}}

FAQ on using the HubSpot MCP with Claude Code

In case you have any more questions, we've addressed several more below.

What your Agent can do with a HubSpot MCP server?

Here are just a few impactful use cases:

• Create and update contacts: add new leads from inbound forms, enrich existing records with research findings

• Manage deals: move deals through pipeline stages, update deal values, assign owners

• Log sales activity: record calls, emails, and meetings against CRM records automatically

• Search and retrieve records: look up contacts by email, filter companies by industry or revenue, find open deals by owner

• Create and update companies: maintain company records as agents gather new firmographic data

Why should I use Merge Agent Handler's HubSpot MCP server over other HubSpot MCP servers?

Merge Agent Handler gives you a production-grade MCP interface to HubSpot without building and maintaining your own connector.

Instead of managing OAuth tokens, handling API versioning, or writing tool schemas by hand, you get a fully maintained HubSpot integration out of the box. The Tool Pack and Registered User model also lets you scope exactly what your agent can access, allowing it to (as an example) read contacts without being able to delete deals.

Merge also handles rate limiting, error normalization, and API changes on your behalf.

Why should I use Claude Code to connect to the HubSpot MCP server?

Claude Code is purpose-built for agentic, terminal-native workflows. If your team lives in the command line, Claude Code lets you pull HubSpot context directly into that environment without switching to a browser or a separate tool.

It's especially powerful for sales engineers and RevOps teams who want to script CRM automation, inspect deal data mid-workflow, or build lightweight agents that interleave HubSpot reads with code execution.

What types of tasks can my agents perform with the HubSpot MCP server?

Agents connected to HubSpot via Merge can handle the full spectrum of CRM automation.

On the read side, they can pull contact histories, summarize deal pipelines, identify stale opportunities, or generate account briefings before a sales call.

On the write side, they can log outreach activity, update deal stages based on email sentiment analysis, create follow-up tasks, and enroll leads into nurture sequences.

More sophisticated agents can combine HubSpot data with external signals. For example, reading a LinkedIn profile, enriching a HubSpot contact record, and drafting a personalized outreach email, all in a single agent run.