Overview

The HubSpot MCP connector enables your Leena AI Agents to integrate with your organization's HubSpot platform, facilitating automated CRM workflows such as searching and retrieving CRM records, running analytical queries, discovering properties, and looking up owners, users, and teams.

The HubSpot MCP server is HubSpot's official remote Model Context Protocol (MCP) server that securely exposes HubSpot CRM data and actions as tools for AI agents. Leena AI connects to it through the MCP connector, allowing Agents to work with CRM objects (contacts, companies, deals, tickets, commerce objects) and engagements, query CRM data with SQL-style analytics, and access organizational context such as users, teams, and owners — all while respecting each user's existing HubSpot permissions.

API Details

Leena AI integrates with the HubSpot MCP server via the Model Context Protocol (MCP) over Streamable HTTP.

MCP server URL: https://mcp.hubspot.com

Documentation link: https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server

Setup

The HubSpot MCP server is connected through Leena AI's MCP connector. The connector supports the following authentication types: No authentication, Custom auth (static headers), Admin OAuth 2.0, and User OAuth 2.0.

The HubSpot MCP server uses OAuth 2.0 (with PKCE) through an app created on the HubSpot developer platform. For HubSpot MCP, use:

• User OAuth 2.0 (recommended): Each employee signs in with their own HubSpot account, selects the HubSpot account to connect, and every action runs with that user's existing HubSpot permissions.

The scopes granted are determined automatically by the tools available in the MCP server at the time of installation and by the permissions the user chooses to grant during installation.

Prerequisites

Before setting up the HubSpot MCP connector, ensure you have:

• A HubSpot account and access to the HubSpot developer platform (the remote MCP server requires the new HubSpot Developer Platform)
• Ability to create an app on the developer platform with the appropriate CRM scopes
• HubSpot users (with appropriate CRM permissions) for the employees who will use the actions
• Access to your Leena AI workspace with connector management permissions

Get credentials

Here is how to get the OAuth credentials of your HubSpot app:

1. Log in to your HubSpot developer account
2. Create an app on the HubSpot developer platform (a user-level app with the appropriate CRM read scopes)
3. Configure the app's auth settings:
   1. Add the Redirect URL — this will be filled later from Leena AI
   2. Note the app's Client ID and Client secret (keep the secret secure)

Add connection

Here is how to add a connection on Leena AI:

1. Log in to your Leena AI workspace
2. Navigate to Settings > Integrations
3. Search for "Custom MCP" and select it from the list to add its new connector
4. Give the connection a name (for example, "HubSpot MCP")
5. Start configuring the connector
   1. MCP remote URL: The HubSpot MCP server URL — https://mcp.hubspot.com
   2. Authentication type: Select "User OAuth 2.0"
6. Fill in the OAuth fields:
   1. Redirect URI: The callback URL for the OAuth flow (auto-generated by Leena AI)
   2. Client ID: Your HubSpot app's client ID
   3. Client secret: Your HubSpot app's client secret
7. Copy the Redirect URI and update the HubSpot app
   1. Copy the auto-generated Redirect URI from Leena AI
   2. Go back to your HubSpot app's auth settings and add it as a Redirect URL
   3. Save the changes
8. Complete the OAuth flow and save the configuration
   1. Click Connect in Leena AI for the HubSpot MCP connection
   2. You'll be redirected to HubSpot's authorization page
   3. Select the HubSpot account to connect and review the requested permissions
   4. Click Authorize to grant access
   5. You'll be redirected back to Leena AI with a successful connection
   6. The connector will be saved
9. Once the connection is authorized, the available actions are fetched automatically from the HubSpot MCP server and can be selected while building skills (workflows)

Actions

Actions for this connector are discovered dynamically from the HubSpot MCP server. Every action runs with the authenticated user's existing HubSpot permissions — object types and tools that the user cannot access in HubSpot are not available to the Agent either (the get_user_details action reports per-object read/write availability).

The following key actions are supported for the HubSpot MCP connector:

get_user_details

Returns the current user's details, team and hub information, and the availability of CRM object types and tools. This action should be used before other HubSpot actions to determine the user's identity and permissions. Here are some common use cases:

• Connection Check: Verify the connected account and user after setup
• Permission Discovery: Check per-object read/write availability before running other actions
• Personal Context: Get the user's owner ID, primary team, and role for "my" queries

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

This action has no mandatory input parameters.

Optional

Here is a sample JSON input:

{
  "include": ["USER_INFORMATION", "TOOL_INFORMATION"]
}

Response

The action returns:

• The current user's details (owner ID, name, email)
• The account/hub the app is installed in
• CRM object type availability (read and write status per object type)
• Tool availability for the other MCP actions
• Team memberships and roles (when requested)

get_organization_details

Lists organization-wide teams, seats, job titles (roles), and account information such as timezone and currency. Here are some common use cases:

• Team Structure: Look up teams and their members across the organization
• Role Discovery: List job titles to filter users by role
• Account Context: Get the account's timezone and currency before reporting

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

This action has no mandatory input parameters.

Optional

Here is a sample JSON input:

{
  "include": ["TEAMS", "ACCOUNT_INFORMATION"]
}

Response

The action returns the requested sections:

• Teams with names, member owner IDs, and metadata
• Seat type names available in the organization
• Job titles present in the organization
• Account information (timezone, currency, account type, UI domain, account ID)

search_crm_objects

Searches and retrieves CRM records based on filters and criteria — free-text search, property filter groups, and association filters — with sorting and pagination. Here are some common use cases:

• Record Lookup: Find a contact, company, deal, or ticket by name, email, or other properties
• Filtered Lists: List records matching property conditions (e.g. deals in a stage, tickets by priority)
• Association Queries: Find records related to a specific object (e.g. contacts associated with a company)
• Counts: Use the returned total to answer "how many" questions

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "objectType": "deals",
  "filterGroups": [
    {
      "filters": [
        {"propertyName": "dealstage", "operator": "EQ", "value": "closedwon"}
      ]
    }
  ],
  "properties": ["dealname", "amount", "deal_currency_code", "closedate"],
  "sorts": [{"propertyName": "closedate", "direction": "DESCENDING"}],
  "limit": 10
}

Response

The action returns a list of matching CRM records, each containing:

• Record ID
• The requested property values
• A URL template to view the record in HubSpot
• The total count of records matching the criteria and the pagination offset

get_crm_objects

Fetches multiple CRM objects of the same object type in a single request by their IDs. Here are some common use cases:

• Batch Retrieval: Fetch full details for records found via search
• Data Model Discovery: Retrieve records without specifying properties to understand the object's structure
• Record Refresh: Re-fetch specific records after updates

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "objectType": "contacts",
  "objectIds": [1234567890],
  "properties": ["firstname", "lastname", "email", "company"]
}

Response

The action returns the requested CRM objects, each containing:

• Record ID and property values
• Created and last-updated timestamps
• A URL to view the record in HubSpot

query_crm_data

Queries HubSpot CRM data using SQL with HubSpot-specific extensions — aggregations, GROUP BY with DATE_TRUNC intervals, cross-object references (e.g. COMPANY.name from a CONTACT query), and list membership filters. One object type per query; JOINs, UNIONs, and subqueries are not supported. Here are some common use cases:

• Analytics: Aggregate deals, tickets, or contacts by stage, owner, or time period
• Reporting: Build counts, sums, and medians grouped by month or quarter
• Cross-object Insights: Report on records together with an associated object's properties

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "sql": "SELECT dealstage, COUNT(*) FROM DEAL WHERE closedate BETWEEN '2026-01-01' AND '2026-06-30' GROUP BY dealstage",
  "verbosityLevel": "MEDIUM"
}

Response

The action returns the query results:

• Rows of the selected/aggregated values
• Citation links to the underlying records (in MEDIUM/HIGH verbosity)

search_properties

Finds the most relevant CRM property definitions using keyword-based search, or lists all property definitions for an object type when no keywords are provided. Here are some common use cases:

• Property Discovery: Find the internal property name for a business term (e.g. "urgency" on tickets)
• Query Preparation: Confirm property names before using them in searches or SQL queries
• Schema Exploration: List all properties available on an object type

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "objectType": "TICKET",
  "keywords": ["urgency", "priority"]
}

Response

The action returns a list of matching property definitions, each containing:

• Property name (internal identifier) and display label
• Description
• Relevance match score (when keywords are provided)

get_properties

Fetches full property definitions, including data types and enumeration values. Here are some common use cases:

• Valid Values: Discover the valid options of an enumeration property (e.g. deal stages, pipelines)
• Type Checks: Confirm a property's data type before filtering or writing queries
• Field Documentation: Retrieve labels and descriptions for reporting

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "objectType": "deals",
  "propertyNames": ["dealstage", "pipeline"]
}

Response

The action returns the property definitions, each containing:

• Property name, label, and description
• Data type (string, enumeration, number, etc.)
• Valid values with labels (for enumeration types)

search_owners

Lists and searches for owners who can be assigned to CRM records, by name/email or by direct owner-ID lookup. Here are some common use cases:

• Owner Resolution: Find the owner ID for a person before filtering records by owner
• "My records" Queries: Resolve the requesting user's owner ID for ownership filters
• Roster Review: List active owners in the account

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

This action has no mandatory input parameters.

Optional

Here is a sample JSON input:

{
  "searchQuery": "John Smith",
  "limit": 25
}

Response

The action returns a list of owners, each containing:

• Owner ID (used for owner assignments and filters)
• Display name
• Active status

Other available actions

In addition to the key actions above, the following actions are discovered from the HubSpot MCP server and can be used in skills (workflows). Availability depends on the tools enabled for the connection and the user's HubSpot permissions: