# Hand-offs to HubSpot's own agent tooling

This skill plans; HubSpot's official tools do record-level work. Everything below was checked against HubSpot's live docs and the public repository on 2026-10-17. Tool names and commands change, especially in beta, so read the current page before relying on one.

## Remote HubSpot MCP server

- Endpoint `https://mcp.hubspot.com`, generally available to all HubSpot accounts since 13 April 2026, authenticated with OAuth 2.1 and PKCE. HubSpot's assistant connectors run on it. A custom client is configured with its own client ID, client secret and redirect URL.
- It acts in the account on the signed-in user's behalf. Run `get_user_details` first: it returns the user, the account and read and write access per object. Tool availability varies by account, scopes and client, so read the live list rather than this file.
- Reads documented: contacts, companies, deals, tickets, leads, users, custom objects, segments, activities (calls, emails, meetings, notes, tasks), content and campaigns, marketing emails, conversations, and some revenue objects in beta.
- Writes documented: CRM records including custom objects, activities, landing pages, website pages and blog posts (including publishing), campaigns, marketing email drafts, pipelines, custom properties, static and dynamic segments, and quotes in beta. No delete tool is documented.
- Confirmation is per tool, not server-wide:
  - `manage_crm_objects` shows a proposed-changes summary and needs explicit confirmation before every create or update.
  - `manage_segment` needs confirmation before each write. `manage_campaign_objects` needs confirmation before creating or modifying campaigns. Some page and blog actions need confirmation for create and publish.
  - `manage_custom_properties` ("Create custom properties for CRM objects"), `manage_custom_pipelines` ("Create and manage pipelines") and `manage_marketing_email` document no confirmation step. Do not call them from this skill.
- Retrieval limits that matter for inventories: `get_crm_objects` takes up to 100 IDs per request; `search_crm_objects` returns up to 200 results per page with up to five filter groups of six filters.
- If Sensitive Data is on, activities and conversations are blocked from the MCP server (standard CRM APIs are unaffected).

Step-to-tool map (read-only):

- Steps 2 and 3: `get_user_details`, then `get_organization_details` (teams, job titles, seat counts, time zone and account information) for the seat map and account defaults.
- Step 2: `manage_onboarding` assesses the account's onboarding status. Treat its assessment as an input to the capability register, never as a substitute for the gates, and do not let it carry out onboarding steps.
- Step 4: `discover_hubspot_schema` for object types, `get_properties` and `search_properties` for the property inventory.
- Steps 3 and 6: `search_owners` to check every owner in the import files exists.
- Counts per object and per stage: `query_crm_data` (the page asks for `tool_guidance` and `search_properties` first). State whether more pages remain; never present a first page as the whole portal.
- Check a proposed import mapping against existing properties.

Out of bounds in this skill, even though the tools exist: `manage_crm_objects`, `manage_segment`, `manage_custom_properties`, `manage_custom_pipelines` and any page, email or campaign write. Produce the change list and let the HubSpot admin apply it after approval.

Connector settings for assistant apps (checked 2026-10-17):

- Set write tools to "Needs Approval". "Always allow" lets edits happen without a prompt.
- Bulk create or update is limited to 10 records at a time, and the connectors do not delete.
- HubSpot's assistant connectors differ in which validation rules they apply (see the connector pages in `sources.yaml`). Test a write that should be rejected in each client the team uses.
- Installing without prior approval needs Super Admin or App Marketplace Access; other users need a Super Admin to approve the connector first.

## HubSpot Agent CLI (beta) and agent-cli-skills

- The `hubspot` command (distinct from the `hs` developer CLI). Beta: commands, flags and behaviour may change without notice, and using it means accepting HubSpot's developer beta terms.
- Standard mode: `hubspot auth login` opens a browser OAuth flow and access mirrors the user's permissions. `hubspot whoami` shows the session.
- Admin mode: a service key in `HUBSPOT_ACCESS_TOKEN` gives account-level access with no per-user audit trail. Do not use admin mode for implementation work driven by an agent; never paste a key into a conversation.
- Commands that need Admin mode, per the guide:
  - Every `schemas` command (`list`, `get`, `create`, `update`, `delete`) requires Admin mode via a service key.
  - `objects delete`, `pipelines delete`, `pipelines stages-delete`, `properties delete`, `associations labels-create`, `labels-update` and `labels-delete`, and several batch and limits commands, may require it.
- Because this skill's hand-off excludes Admin mode, custom object schema changes, pipeline and property deletes and association-label changes go to a human admin in the HubSpot UI, not to the CLI.
- Every write command supports `--dry-run`. `schemas update`, `schemas delete`, `workflows update`, `workflows delete` and `views delete` need a dry-run digest; `--confirm` is documented for `views delete` and `reports delete`.
- `objects merge` folds the secondary into the primary and deletes the secondary. It is irreversible in HubSpot.
- `hubspot history` shows the local audit log for destructive operations only, on the operator's machine. Creates and updates do not appear there, so save the CLI output of every create and update run with the change record.
- Super Admins can use App Governance (beta) to control who can connect the CLI.
- Skills: `npx skills add hubspot/agent-cli-skills` installs 18 Apache-2.0 skills. Read `bulk-operations` first (JSONL, pagination, dry-run, digest and confirm, history recovery). Others relevant here: `crm-lookup`, `crm-data-quality` (dedupes through `objects merge`), `data-enrichment` (matches through `objects upsert`), `deal-management`, `team-ownership`, `workflow-automation` (creates, updates and deletes workflows), `sales-reporting`, `quote-to-cash`. `custom-object-management` relies on `schemas` commands, so it falls outside this hand-off.

Hand-off pattern for an approved change:

1. This skill produces the change file (CSV or JSONL) and the expected result per row.
2. The operator runs the matching CLI command with `--dry-run` and compares the preview with the expected result.
3. A human approves; the operator runs the real command on a small batch first.
4. Re-read the records and check workflows they could trigger. Keep the saved CLI output of the run, plus `hubspot history` for any destructive operation, with the change record.
5. Within 14 days, a Super Admin can roll back a named import, integration or workflow with Restore CRM changes. The docs do not say whether a CLI write can be selected there, so plan recovery from the saved output and the before-export.

Merges, schema deletes and workflow deletes are never run from this skill's output without a named approver.

## Docs for the agent

- Developer docs index: `https://developers.hubspot.com/docs/llms.txt` (pages are also served as `.md`).
- Knowledge base: `https://knowledge.hubspot.com/` (`/llms.txt` returned 404 on 2026-10-17, so fetch article pages directly).
- `sources.yaml` lists a developer-docs MCP endpoint recorded during research. It answered a plain GET with 405, which is normal for an MCP endpoint but does not prove the tool list; run an MCP initialize before relying on it.
- HubSpot describes the local Developer MCP server as a separate tool for building apps and CMS content; it is not the documented route for CRM record work.
- Changelog: `https://developers.hubspot.com/changelog`.