Connect your AI Agents to HubSpot in minutes
Available tools
get_deal_associations
Get all associations (emails, notes, calls, meetings, tasks) for a specific deal. Use this to find activities related to a deal, such as 'get all emails for the Acme Markets deal' or 'list notes associated with deal 12345'. Returns the IDs and metadata of associated objects which can then be fetched individually for full details.
list_deal_notes
Get all notes for a deal with full content and HubSpot UI URLs. Returns note details with clickable links to view in HubSpot. Use for 'show notes on Acme deal with links'.
list_deal_calls
Get all calls for a deal with full details and HubSpot UI URLs. Returns call info (duration, outcome, notes) with clickable links. Use for 'show calls on Acme deal with links'.
list_deal_meetings
Get all meetings for a deal with full details and HubSpot UI URLs. Returns meeting info (title, attendees, time) with clickable links. Use for 'show meetings on Acme deal with links'.
list_deal_tasks
Get all tasks for a deal with full details and HubSpot UI URLs. Returns task info (status, due date, assignee) with clickable links. Use for 'show tasks on Acme deal with links'.
list_deal_emails
Get all emails for a deal with full content and HubSpot UI URLs. Returns email info (subject, body, sender) with clickable links. Use for 'show emails on Acme deal with links'.
list_deal_activities
Get ALL activities (emails, notes, calls, meetings, tasks) for a deal with HubSpot UI URLs. Returns complete timeline with clickable links. Use for 'show everything on Acme deal with links'.
get_company_associations
Get all associations (emails, notes, calls, meetings, tasks) for a specific company. Use this to find activities related to a company, such as 'get all emails for Acme Corp' or 'list notes associated with company 12345'. Returns the IDs and metadata of associated objects.
list_company_notes
Get all notes for a company with full content and HubSpot UI URLs. Returns note details with clickable links to view in HubSpot. Use for 'show notes on Acme Corp with links'.
list_company_calls
Get all calls for a company with full details and HubSpot UI URLs. Returns call info (duration, outcome, notes) with clickable links. Use for 'show calls on Acme Corp with links'.
list_company_meetings
Get all meetings for a company with full details and HubSpot UI URLs. Returns meeting info (title, attendees, time) with clickable links. Use for 'show meetings on Acme Corp with links'.
list_company_tasks
Get all tasks for a company with full details and HubSpot UI URLs. Returns task info (status, due date, assignee) with clickable links. Use for 'show tasks on Acme Corp with links'.
How to set up Merge Agent Handler
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}FAQs on using Merge's HubSpot MCP server
FAQs on using Merge's HubSpot MCP server
Who is the HubSpot MCP server for?
It can be used for endless AI assistants, agents, and third-party AI/automation apps.
How can I use the HubSpot MCP server?
The use cases naturally depend on the agent you've built, but here are a few common ones:
- Automated contact enrichment: Your agent can automatically enrich HubSpot contacts with additional data when new leads are created, such as company information, social profiles, and engagement history
- Real-time deal updates: As sales reps engage with prospects, your agent can automatically update deal properties in HubSpot, including deal stage, amount, expected close date, and custom fields
- Marketing intelligence: Your agent can help marketing teams create custom reports on campaign performance via HubSpot data. For example, a marketing manager can ask for a conversion rate report, and the agent can use fields like campaign names, lead sources, and conversion metrics to create them
- Email sequence optimization: Your agent can generate personalized email sequences by pulling data from the relevant HubSpot contact and deal records and by leveraging similar successful sequences from other prospects
What are popular tools for HubSpot’s MCP server?
Here are just a few popular tools across data types:
Deals
- <code class="blog_inline-code">get_deal_associations</code>
- <code class="blog_inline-code">list_deal_notes</code>
- <code class="blog_inline-code">list_deal_calls</code>
- <code class="blog_inline-code">list_deal_activities</code>
Companies
- <code class="blog_inline-code">list_company_tasks</code>
- <code class="blog_inline-code">get_company_associations</code>
- <code class="blog_inline-code">list_company_emails</code>
Tasks
- <code class="blog_inline-code">get_task</code>
- <code class="blog_inline-code">update_task</code>
- <code class="blog_inline-code">delete_task</code>
- <code class="blog_inline-code">list_task</code>
Can I set custom security rules for HubSpot tool calls in Merge Agent Handler?
Yes, you can apply custom security rules to HubSpot tool calls. Merge's security gateway and data loss prevention (DLP) applies to all connectors, including HubSpot.
Here are just a few examples:
- Credit card numbers: Block any HubSpot contact or deal updates that contain credit card numbers in fields like notes or descriptions
- Social security numbers: Prevent your agents from adding SSNs to HubSpot contact records or deal properties
- Email addresses: Redact email addresses when agents retrieve or search HubSpot contacts, so they only see masked versions (e.g., j*@merge.dev)
- Phone numbers: Automatically redact phone numbers from HubSpot contact details when agents retrieve them
- API keys and tokens: Block agents from posting authentication credentials or access tokens in HubSpot deal notes or contact properties
- Internal account IDs: Mask sensitive customer identifiers when agents read or update HubSpot records to prevent cross-account information leakage
You can configure these rules to block, redact, or log sensitive data, and they apply across all tool calls made to HubSpot through Agent Handler.
What makes Merge Agent Handler’s HubSpot MCP server better than alternative HubSpot MCP servers?
Here are some of the top reasons:
- Enterprise-grade authentication handling: Merge manages OAuth, credential lifecycle, and secure connector onboarding via Merge Link. This lets your agent avoid handling tokens directly
- Security gateway and data loss prevention: Merge scans all HubSpot tool inputs/outputs for sensitive data (e.g., PII, credentials) and can block, redact, or mask content
- Real-time observability and audit trail: Agent Handler logs every tool call and every underlying API request, and provides fully searchable logs
- Tool Pack configuration and multi-connector orchestration: Merge allows you to bundle HubSpot with other systems (Salesforce, Jira, Slack, etc.) with per-agent permission controls
How can I add tools to Merge Agent Handler’s HubSpot MCP server?
You can customize or expand the HubSpot connector using Connector Studio and Tool Packs. Here's how:
In Connector Studio
- Log into the Agent Handler dashboard.
- Navigate to Connector Studio in the sidebar.
- Select the HubSpot connector.
- From there, you can customize the connector.
In the Tool Pack configuration
- Create or select a Tool Pack (Navigate to "Tool Packs" in the sidebar).
- Add the HubSpot connector to your Tool Pack by clicking "Add Connector".
- Enable or disable specific HubSpot tools as needed for your use case.
- Save your changes. The HubSpot connector and its tools are now available in your Tool Pack.
Explore other MCP servers built and managed by Merge
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
