--- name: iblai-connect-hubspot description: "Read and write HubSpot data through the HubSpot CRM API (Objects API v3) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with HubSpot data, or to set up a HubSpot MCP connection on ibl.ai." metadata: kind: guide --- # HubSpot connector for AI agents > A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/hubspot — not part of the iblai/vibe repository. Checked against HubSpot, Inc.'s documentation on October 20, 2026; test it against your own HubSpot setup before you rely on it. HubSpot is a CRM platform with marketing, sales and service tools. It stores contacts, companies, deals, tickets, line items, products, activities (calls, emails, meetings, notes, tasks) and custom objects. ## Auth & conventions - **API:** HubSpot CRM API (Objects API v3) (REST). CRUD, batch (up to 100 inputs), search and associations for CRM objects at /crm/v3/objects/{objectType}: contacts, companies, deals, tickets, activities, custom objects and 40+ other types. Cursor paging via limit and after. - **Base URL:** https://api.hubapi.com/ - **Access:** Public, self-serve. Any account can use the API. A super admin creates a legacy private app (Development > Legacy apps) to get a static access token, or a developer builds an app that uses OAuth. - **Auth:** Private app access token (Bearer); OAuth 2.0 authorization code; OAuth 2.1 with PKCE (remote MCP server). Private app tokens are sent as Authorization: Bearer and limited to the scopes picked at creation. OAuth tokens come from https://api.hubapi.com/oauth/v1/token and expire after 30 minutes; refresh tokens renew them. - **Limits:** Private apps: 100 req/10s and 250,000/day (Free/Starter), 190/10s with 625,000/day (Professional) or 1,000,000/day (Enterprise). Public OAuth apps: 110 req/10s per installing account. Over-limit returns 429. - Keep HubSpot credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file. - Destructive or outward-facing calls are marked **Confirm with the user first** — do. ## Reads - **Contacts and companies** — GET /crm/v3/objects/contacts and /companies, with properties, property history and associations. - **Deals and pipelines** — Read deals with stage, amount and associated contacts or companies via the Objects API. - **Tickets** — Read support tickets and their associated records via /crm/v3/objects/tickets. - **Activities** — Calls, emails, meetings, notes and tasks attached to CRM records. - **Search results** — POST to an object's /search endpoint with property filter groups. ## Writes - **Create or update records** — POST, PATCH and batch create/update/upsert on contacts, companies, deals, tickets and other objects. - **Associations** — Link records to each other, e.g. a contact to a deal. - **Log activities** — Create notes, tasks, calls and meetings on a record. - **Archive records** — DELETE /{recordId} or POST /batch/archive removes records. **Confirm with the user first.** ## Expose it to an ibl.ai agent (MCP) HubSpot, Inc. publishes an official MCP server, HubSpot MCP server (remote) (https://developers.hubspot.com/docs/build-with-ai/remote-mcp-server). Register it below as-is, or host your own server that wraps the calls in this skill. First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`): ```bash npx skills add iblai/vibe --all # then, in your coding agent: /iblai-api-login ``` Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`. 1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`. - HubSpot supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first. 2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back. 3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged. Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill. ## Example prompts - "Find contacts in the lead lifecycle stage with no activity in the last 60 days" - "Show deals in our sales pipeline that are past their close date" - "Log a note on Acme Corp's company record summarizing today's call" - "Create a ticket for jane@example.com about a billing question" ## Guardrails - CRM records hold personal data about contacts (names, emails, phones, activity history). HubSpot blocks activity objects over MCP when the account's sensitive data setting is on. - Request the narrowest HubSpot scopes or role the task needs, and prefer a read-only credential for agents that only answer questions. - Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request. - Before any write, show the user exactly what will change and wait for a yes. - Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop. ## References - HubSpot MCP server: https://developers.hubspot.com/docs/build-with-ai/remote-mcp-server - CRM Objects API v3 guide: https://developers.hubspot.com/docs/api-reference/crm-objects-v3/guide - API usage guidelines and limits: https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines - HubSpot MCP server (remote): https://developers.hubspot.com/docs/build-with-ai/remote-mcp-server - This connector on ibl.ai: https://ibl.ai/developer/connectors/hubspot - ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections