HubSpot

intent

use this skill to query, read, and modify hubspot crm records (contacts, companies, deals, tickets, associations, owners, pipelines) through hubspot's official mcp server. the skill is a thin pass-through to hubspot's hosted mcp endpoint at https://mcp.hubspot.com. call it when the user asks about hubspot customer data, pipeline state, deal status, ticket status, account ownership, or any crm activity. the live server is the source of truth for available tools, their names, parameters, and usage instructions.

inputs

external connection: hubspot mcp server

• endpoint: https://mcp.hubspot.com
• protocol: https, oauth 2.0 with pkce
• scope: defined by the hubspot oauth grant (the connected account determines what data is readable and writable)

environment variables (required at setup time)

• MAVERICK_HUBSPOT_MCP_REFRESH_TOKEN: oauth refresh token issued by hubspot
• MAVERICK_HUBSPOT_MCP_CLIENT_ID: mcp auth app client id from hubspot
• MAVERICK_HUBSPOT_MCP_CLIENT_SECRET: mcp auth app client secret from hubspot
• MAVERICK_HUBSPOT_MCP_ACCESS_TOKEN: current access token (mcporter manages this)

environment variables (optional, metadata for token refresh)

• MAVERICK_HUBSPOT_MCP_EXPIRES_AT: unix timestamp when access token expires
• MAVERICK_HUBSPOT_MCP_EXPIRES_IN: seconds until access token expires
• MAVERICK_HUBSPOT_MCP_REFRESH_TOKEN_EXPIRES_AT: unix timestamp when refresh token expires

runtime requirements

• mcporter >= v0.11.0 on PATH (handles oauth token refresh, vault storage, mcp protocol)
• mcporter config file at {baseDir}/mcporter.json (created by setup script)
• hubspot oauth grant must be active in the connected hubspot account (not revoked)

procedure

step 1: discover live tool catalog and server instructions

input: mcporter binary, config file, skill credentials in vault

run:

mcporter --config {baseDir}/mcporter.json list maverick-hubspot-mcp --schema

output: json object containing Instructions: field (if published by server) and full json schema for every available tool, including parameter names, types, descriptions, and required fields

action: treat this output as authoritative. do not rely on tool names or parameters from memory. if the server publishes usage instructions in the Instructions: field, read and follow them for the rest of the session.

edge case: if the list command fails with auth errors (e.g., "invalid grant", "token expired"), the oauth grant may be revoked or refresh tokens may be invalid. see decision points.

step 2: call a tool from the live catalog

input: tool name from step 1 catalog, tool arguments matching the schema, mcporter config

form: maverick-hubspot-mcp.<tool_name>

run:

mcporter --config {baseDir}/mcporter.json call maverick-hubspot-mcp.<tool_name> <arg_key>=<arg_value> ...

output: raw tool response (text, json, or structured output depending on the tool)

optional: add --output json flag to force structured json output and wrap any transport errors in json envelopes:

mcporter --config {baseDir}/mcporter.json call --output json maverick-hubspot-mcp.<tool_name> ...

action: inspect the response for success. if the tool modifies data (create, update, delete), confirm the change matches the user's intent before proceeding to the next step.

edge case: if the call fails with "unknown tool" or parameter errors, re-run step 1 to verify the tool name and schema. hubspot mcp server updates may have changed the catalog.

edge case: if the call fails with rate limit errors (http 429 or hubspot rate limit responses), wait 60 seconds and retry. hubspot has per-minute and per-day rate limits depending on account tier.

edge case: if the call times out or fails with network errors, retry once after 5 seconds. transient network issues are normal.

step 3: interpret the response and act on user intent

input: tool response from step 2, user's original goal

action: extract relevant data from the response. if the response is a record list, filter or summarize based on what the user asked for. if the response is a single record, present the key fields to the user. if the response is a write confirmation (e.g., "contact updated"), confirm the change to the user.

output: user-facing summary or structured data (record id, contact name, deal stage, etc.)

edge case: if the response is empty (e.g., search returned no results, contact has no associated deals), state this clearly to the user. do not invent data.

decision points

if oauth grant is revoked or invalid: the user revoked access in hubspot's integrations ui, or credentials were never authorized. mcporter will fail all tool calls with persistent auth errors (e.g., "invalid grant", "unauthorized").

action: surface the error to the user. ask them to re-authorize the integration by visiting hubspot's integrations ui and granting consent to the mcp auth app again. once authorized, the setup script must be re-run with fresh oauth credentials to update the vault.

do not attempt to call tools if auth is broken.

if the refresh token has expired: hubspot refresh tokens have a lifetime. if the refresh token expires, mcporter cannot issue new access tokens.

signal: calls fail with auth errors that persist across multiple retries; mcporter logs mention "refresh token invalid" or "grant revoked".

action: ask the user to re-authorize the integration in hubspot's ui. once re-authorized, extract the new oauth credentials and re-run setup:

bash scripts/setup.sh

setup is idempotent for valid credentials but destructive for stale ones. do not re-run setup with old credentials.

if the user asks for an operation not in the live catalog: the mcp server does not expose a tool for the requested operation (e.g., no tool to create custom objects, no bulk export tool).

action: inform the user that the operation is not available through this skill. suggest alternative approaches (e.g., "you can read contacts one at a time and export the results manually", or "this operation requires direct hubspot api access or the web ui"). do not invent tools that do not exist in the catalog.

if the mcp server is unreachable: network failure, dns failure, or hubspot's hosted mcp endpoint is down.

signal: mcporter fails all calls with network errors (e.g., "connection refused", "dns lookup failed").

action: retry once after 10 seconds. if the failure persists, inform the user that hubspot's mcp server is unreachable. suggest checking hubspot's status page or retrying later.

if a write operation conflicts with existing data: a create or update operation fails because a required field is missing, or the record state has changed since the user last read it.

signal: tool call fails with validation or conflict errors (e.g., "missing required property: email", "record was modified by another user").

action: if validation: re-read the live schema and ask the user for the missing field. if conflict: re-read the current record state and ask the user how to resolve the conflict (overwrite, abort, merge).

if the user provides sensitive data unrelated to hubspot: e.g., the user includes a credit card number, password, or api key in a tool argument.

action: warn the user that tool arguments transit hubspot's mcp server over https and may be logged. do not pass unrelated sensitive content through tool arguments. ask the user to provide only hubspot-relevant data.

output contract

tool discovery (step 1 output)

• format: json object
• fields: tools array (each tool has name, description, inputSchema), optional Instructions string
• location: stdout
• success signal: json parses, tools array is non-empty, server instructions (if any) are readable

tool call (step 2 output)

• format: depends on the tool (text, json, csv, or structured object)
• with --output json: always json, even on error (errors wrapped in error field)
• location: stdout
• success signal: mcporter exit code 0; if json output, no error field; if text output, no "error" or "fatal" keywords

user-facing summary (step 3 output)

• format: plain text, structured list, or markdown table (as appropriate for the data)
• fields: record type (contact, company, deal, ticket), id, key properties (name, email, stage, status), associations (company linked to contact, owner assigned to deal)
• location: user message
• success signal: user can understand the result without ambiguity; all requested fields are present or explicitly noted as missing

outcome signal

the skill worked if:

1. step 1 completes without auth errors and returns a non-empty tool catalog. the user can see what tools are available.
2. step 2 completes and returns a response matching the tool's documented output type (not a generic error).
3. step 3 delivers data or confirmation that matches the user's original request. the user understands what happened and what the data means.

if the user asks a follow-up question about the same record or operation and you can answer it without re-calling a tool (because step 2 returned all the necessary data), you have confidence that the outcome is complete.

if any step fails, the outcome signal is missing: the user receives an error message, the skill stops, and you ask for clarification or offer alternatives.