HubSpot API Patterns

HubSpot MCP Tools & API Patterns

Overview

HubSpot provides a first-party remote MCP server at https://mcp.hubspot.com/ for AI tool integration. The MCP server uses OAuth 2.0 with PKCE for authentication and Streamable HTTP as its transport protocol. Tools are backed by the HubSpot CRM Search API and cover contacts, companies, deals, tickets, tasks, notes, and associations. This skill covers MCP server connection, the complete tool reference, search patterns, error handling, and best practices.

Anti-triggers

• What properties an object has and what its enum values mean — the field, lifecycle-stage, and pipeline tables live with the object; use hubspot-contacts, hubspot-companies, hubspot-deals, or hubspot-tickets.
• A different hosted OAuth MCP server — the connection shape rhymes but the tenant, scopes, session model, and tools do not; use warmly-api-patterns or pandadoc-api-patterns.

Connection & Authentication

MCP Server

HubSpot hosts an official remote MCP server. Authentication uses OAuth 2.0 with PKCE, handled by the mcp-remote bridge:

1. Go to developers.hubspot.com
2. Navigate to Development > MCP Auth Apps
3. Create a new MCP Auth App
4. Copy the Client ID and Client Secret

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

Transport: Streamable HTTP

Authentication: OAuth 2.0 + PKCE (handled automatically by mcp-remote)

Environment Variables

export HUBSPOT_CLIENT_ID="your-client-id"
export HUBSPOT_CLIENT_SECRET="your-client-secret"

Claude Desktop Configuration

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.hubspot.com/"
      ],
      "env": {
        "HUBSPOT_CLIENT_ID": "YOUR_CLIENT_ID",
        "HUBSPOT_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Scopes

HubSpot MCP automatically derives required OAuth scopes from the tools you use. You do not need to manually configure scopes. For example:

• Using contact tools automatically requests crm.objects.contacts.read and crm.objects.contacts.write
• Using deal tools automatically requests crm.objects.deals.read and crm.objects.deals.write
• Using association tools automatically requests the appropriate association scopes

Sensitive Data

HubSpot MCP excludes sensitive data properties (PHI -- Protected Health Information) from tool responses by default. Properties marked as sensitive in HubSpot settings will not appear in MCP tool results.

Complete MCP Tool Reference

Contact Tools

Company Tools

Deal Tools

Ticket Tools

Activity Tools

Utility Tools

Association Tools

CRM Search API

Search Patterns

HubSpot MCP tools that search records use the CRM Search API under the hood. Search tools accept filterGroups for structured queries:

Filter Group Structure:

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "email",
          "operator": "CONTAINS_TOKEN",
          "value": "acme.com"
        }
      ]
    }
  ]
}

Available Operators

Sorting

{
  "sorts": [
    {
      "propertyName": "createdate",
      "direction": "DESCENDING"
    }
  ]
}

Sort Directions: ASCENDING, DESCENDING

Pagination

Search results use cursor-based pagination:

Iterating through all results:

1. Call the search tool with limit=100
2. Check the response for a paging.next.after value
3. If present, call again with after set to that value
4. Repeat until no paging.next.after is returned

Response Format

Single Resource:

{
  "id": "12345",
  "properties": {
    "firstname": "John",
    "lastname": "Smith",
    "email": "john.smith@acmecorp.com",
    "company": "Acme Corporation",
    "phone": "555-123-4567",
    "lifecyclestage": "customer",
    "createdate": "2025-06-15T10:30:00.000Z",
    "lastmodifieddate": "2026-01-20T14:15:00.000Z"
  },
  "createdAt": "2025-06-15T10:30:00.000Z",
  "updatedAt": "2026-01-20T14:15:00.000Z"
}

Search Results:

{
  "total": 47,
  "results": [
    {
      "id": "12345",
      "properties": {
        "firstname": "John",
        "lastname": "Smith",
        "email": "john.smith@acmecorp.com"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "12345"
    }
  }
}

Rate Limiting

Rate Limit Details

When rate limited, the MCP tool will return a 429 error. Wait before retrying. The MCP server handles OAuth token refresh automatically.

Plan-Based Limits

Error Handling

Common Errors

Troubleshooting MCP Connection

1. Verify credentials - Ensure HUBSPOT_CLIENT_ID and HUBSPOT_CLIENT_SECRET are correct
2. Check URL - MCP server URL must be https://mcp.hubspot.com/
3. Test with a simple call - Try hubspot_get_user_details to verify connectivity
4. Re-authenticate - Restart the MCP connection to force a fresh OAuth flow
5. Check plan - Ensure your HubSpot plan supports the API features you need

Best Practices

1. Filter server-side - Use hubspot_search_* tools with filterGroups instead of listing all records
2. Use maximum page size - Set limit=100 to minimize total tool calls
3. Monitor rate limits - Stay well under 100 requests per 10 seconds
4. Use associations - Link related objects (contacts to companies, deals to contacts) for full context
5. Check properties first - Use list_*_properties tools to discover available fields before searching
6. Validate before creating - Search for existing records before creating duplicates
7. Use lifecycle stages - Track contacts and companies through their lifecycle for accurate reporting
8. Cache property lists - Property definitions change infrequently; reference them across multiple operations

Related Skills

• HubSpot Contacts - Contact management
• HubSpot Companies - Company management
• HubSpot Deals - Deal pipeline management
• HubSpot Tickets - Support ticket management
• HubSpot Activities - Tasks, notes, and associations