diff --git a/guides/hubspot/meta.yaml b/guides/hubspot/meta.yaml index 5264490..72625c8 100644 --- a/guides/hubspot/meta.yaml +++ b/guides/hubspot/meta.yaml @@ -38,68 +38,68 @@ remotes: locator: https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server name: Integrate AI tools with the HubSpot MCP server classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: endpoint-observation locator: https://mcp.hubspot.com/.well-known/oauth-protected-resource classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" provenance: - source: pulsemcp name: com.pulsemcp.mirror/hubspot scope: Speakeasy MCP Catalog status: present classification: mirror - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: provider-documentation locator: https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server name: Integrate AI tools with the HubSpot MCP server classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: provider-documentation locator: https://developers.hubspot.com/docs/llms.txt name: HubSpot developer documentation index classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: provider-documentation locator: https://developers.hubspot.com/ai-tools/mcp name: HubSpot MCP Server classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: provider-documentation locator: https://developers.hubspot.com/changelog/remote-hubspot-mcp-server-is-now-generally-available name: Remote HubSpot MCP server is now generally available classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: provider-documentation locator: https://developers.hubspot.com/changelog/public-beta-self-service-mcp-auth-apps-for-the-hubspot-remote-mcp-server name: "Public Beta: Self-Service MCP Auth Apps for the HubSpot Remote MCP Server" classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: provider-documentation locator: https://developers.hubspot.com/changelog/spring-2026-spotlight name: Spring 2026 Spotlight classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: provider-documentation locator: https://developers.hubspot.com/changelog/june-2026-rollup name: Developer updates for June 2026 classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: provider-documentation locator: https://knowledge.hubspot.com/user-management/hubspot-user-permissions-guide name: HubSpot user permissions guide classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: endpoint-observation locator: https://mcp.hubspot.com/.well-known/oauth-protected-resource classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: endpoint-observation locator: https://mcp.hubspot.com/.well-known/oauth-authorization-server classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" - source: repository-doctrine locator: doctrine/speakeasy-setup.md name: Speakeasy setup canonical section classification: official - observed_at: "2026-07-28T18:22:41Z" + observed_at: "2026-08-11T15:40:29Z" diff --git a/guides/hubspot/research.md b/guides/hubspot/research.md index 5f23141..79a3784 100644 --- a/guides/hubspot/research.md +++ b/guides/hubspot/research.md @@ -1,7 +1,7 @@ --- research_version: 1 slug: hubspot -researched_at: 2026-07-28T18:22:41Z +researched_at: 2026-08-11T15:40:29Z --- # HubSpot — Research Dossier @@ -20,11 +20,11 @@ only for two facts no other source states: the admin-connects-first behavior and the Sensitive Data Properties restriction, both flagged where used. The developer changelog is used for product status and for capability changes newer than the setup page. The primary setup page, its -newly published documentation index, the permissions guide, and the live -OAuth metadata were reverified at `2026-07-28T18:22:41Z`. The operator also -confirmed that the Speakeasy MCP Catalog contains -`com.pulsemcp.mirror/hubspot`, titled **HubSpot**, so this Guide uses only the -catalog add-server path. +documentation index, the permissions guide, and the live OAuth metadata were +reverified at `2026-08-11T15:40:29Z`. +The operator forced the Speakeasy MCP Catalog path and supplied the matched +record `com.pulsemcp.mirror/hubspot`, titled **HubSpot**, so this Guide renders +only the catalog add-server path. ## Server facts @@ -103,10 +103,13 @@ catalog add-server path. users, carts, invoices, orders, line items, products, quotes, subscriptions, and segments (lists)"; "Activities: calls, emails, meetings, notes, and tasks"; "Content and marketing: blog posts, - landing pages, site pages, campaigns, and marketing events." + landing pages, site pages, campaigns, and marketing events"; + conversations in supported inbox/help-desk channels, subject to inbox + access restrictions; and marketing-email drafts, previews, analytics, + account health diagnostics, and per-contact delivery/engagement details. - Write access — "CRM records: contacts, companies, deals, tickets, line items, and products"; "Activities: calls, emails, meetings, - notes, and tasks." + notes, and tasks"; and marketing-email draft creation and updates. - **Recorded conflict / newer capability**: the June 2026 developer rollup (2026-06-29) adds landing-page write: "Starting from an existing template or a clone of a page you already have, AI @@ -120,13 +123,15 @@ catalog add-server path. scenes, the HubSpot MCP server is based on the CRM search API, which currently doesn't include vector search capabilities." See {#keyword-search-only}. -- **Sensitive data** (setup page warning, verbatim): "If your HubSpot +- **Sensitive data** (setup page warning, verbatim): "if your HubSpot account has Sensitive Data turned on, activity objects (such as calls, - emails, meetings, notes, and tasks) will be blocked from access - through the MCP server." The overview page adds: "The HubSpot MCP - server doesn't allow access to custom Sensitive Data Properties, - including Personal Health Information and other forms of Highly - Sensitive Data." See {#sensitive-data-blocks-activities}. + emails, meetings, notes, and tasks) and conversation data will be blocked + from access through the MCP server." The page states this restriction is + MCP-specific and does not apply to the standard CRM APIs. The overview + page adds: "The HubSpot MCP server doesn't allow access to custom + Sensitive Data Properties, including Personal Health Information and + other forms of Highly Sensitive Data." See + {#sensitive-data-blocks-activities}. - **Adjacent products, not this server** (recorded to prevent mis-navigation): the **developer MCP server** is a separate local tool — setup page note, verbatim: "The HubSpot MCP server documented on @@ -237,9 +242,8 @@ is documented except where flagged. - Multiple redirect URLs (setup page, verbatim): "If you're including multiple redirect URLs, the first redirect URL will be used as the default redirect." The dialog steps document a single **Redirect URL** - field; how additional URLs are added is not documented (see open - questions). Keep the Speakeasy AI Control Plane callback as the first - (or only) entry. + field. Keep the Speakeasy AI Control Plane callback as the first (or + only) entry; this setup does not require adding another URL. - Values entered: **App name**, `{{ gram.oauth.callback_url }}` into **Redirect URL**, optional **Description**/**Icon**. Values copied: none yet. @@ -271,7 +275,7 @@ is documented except where flagged. ## Speakeasy setup Canonical source: `doctrine/speakeasy-setup.md`, observed -`2026-07-28T18:22:41Z`. +`2026-08-11T15:40:29Z`. Per-guide values: @@ -356,16 +360,15 @@ tools (June 2026 rollup), existing connected users had to "reconnect or re-authorize to grant the new permission scope. New connections prompt for it automatically." -### Sensitive Data blocks activity objects {#sensitive-data-blocks-activities} +### Sensitive Data blocks activities and conversations {#sensitive-data-blocks-activities} -Setup page warning, verbatim: "If your HubSpot account has Sensitive +Setup page warning, verbatim: "if your HubSpot account has Sensitive Data turned on, activity objects (such as calls, emails, meetings, -notes, and tasks) will be blocked from access through the MCP server." -The overview page adds that "The HubSpot MCP server doesn't allow access -to custom Sensitive Data Properties, including Personal Health -Information and other forms of Highly Sensitive Data." An account using -HubSpot's Sensitive Data features loses MCP access to all activity -records. +notes, and tasks) and conversation data will be blocked from access +through the MCP server." This MCP-specific restriction does not apply to +the standard CRM APIs. The overview page adds that "The HubSpot MCP server +doesn't allow access to custom Sensitive Data Properties, including +Personal Health Information and other forms of Highly Sensitive Data." ### Most content and marketing objects are read-only {#content-write-limits} @@ -437,7 +440,7 @@ admin has connected — are undocumented (see open questions). ## Provenance Source inventory from the sweep. HubSpot publishes three documentation -properties, all checked this run: +properties, all checked on `2026-08-11T15:40:29Z`: - **Developer docs — developers.hubspot.com** (source of truth for this guide): the setup page, the `ai-tools/mcp` overview, and the developer @@ -459,7 +462,7 @@ One entry per source drawn from: - `https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server` ("Integrate AI tools with the HubSpot MCP server") — reobserved at - `2026-07-28T18:22:41Z`. The former alternate path + `2026-08-11T15:40:29Z`. The former alternate path `.../build-apps/integrate-with-hubspot-mcp-server` now 308-redirects here (redirect observed this run; the prior run saw it serve the page verbatim). Backs: endpoint `https://mcp.hubspot.com`, PKCE @@ -470,14 +473,15 @@ One entry per source drawn from: "**Create**"), multiple-redirect default behavior, details-page redirect and **Edit info**, general client connection values (Client ID / Client secret / Redirect URL) and the three-step end-user OAuth - flow, supported-data read/write lists, permissions model, automatic - scopes and re-install behavior, Sensitive Data warning, CRM-search/no - vector search callout, developer-MCP-server distinction note, + flow, supported-data read/write lists (including conversations and + marketing emails), permissions model, automatic scopes and re-install + behavior, Sensitive Data warning (including conversation-data blocking), + CRM-search/no vector search callout, developer-MCP-server distinction note, Streamable HTTP transport (MCP Inspector section), token refresh/expiry behavior. Explicitly checked this run: no beta badge anywhere on the page. - `https://developers.hubspot.com/docs/llms.txt` — observed - `2026-07-28T18:22:41Z`. Backs the developer-documentation sweep and + `2026-08-11T15:40:29Z`. Backs the developer-documentation sweep and confirms the current remote-server setup page as the indexed MCP guide. - `https://developers.hubspot.com/ai-tools/mcp` ("HubSpot MCP Server" overview; canonical target of `https://developers.hubspot.com/mcp`, @@ -515,8 +519,8 @@ One entry per source drawn from: module creation, A/B test setup, or first-time site/account setup"), and existing users needing to "reconnect or re-authorize to grant the new permission scope. New connections prompt for it automatically." - Confirmed this run (targeted changelog search) to still be the newest - MCP-related changelog entry as of 2026-07-23. + Reobserved this run; the current setup page now also documents newer + conversation and marketing-email access directly. - `https://knowledge.hubspot.com/user-management/hubspot-user-permissions-guide` — observed this run. Backs (flagged inference only): the **Developer tools access** permission (Account tab > Settings access) covering @@ -528,15 +532,15 @@ One entry per source drawn from: account administration"), reached via the settings icon > **Users & Teams** > selecting a user. - Pulse catalog record `com.pulsemcp.mirror/hubspot`, title **HubSpot** — - observed `2026-07-28T18:22:41Z` from the operator's Speakeasy MCP Catalog - lookup. Backs catalog presence and the catalog-only add-server path. Prior - research on this record also corroborated the remote URL, - `streamable-http`, and absence of dynamic client registration. + observed `2026-08-11T15:40:29Z` from the operator's forced-catalog match. + Backs the catalog-only add-server path and catalog identity. Prior research + on this record also corroborated the remote URL, `streamable-http`, and + absence of dynamic client registration. - `https://mcp.hubspot.com` + `https://mcp.hubspot.com/.well-known/oauth-protected-resource` + `https://mcp.hubspot.com/.well-known/oauth-authorization-server` — direct endpoint observation reverified at - `2026-07-28T18:22:41Z`. Backs: + `2026-08-11T15:40:29Z`. Backs: 401/Bearer behavior with `resource_metadata` pointer, protected- resource metadata (resource `https://mcp.hubspot.com`, authorization server `https://mcp.hubspot.com`, `scopes_supported: []`, @@ -544,5 +548,5 @@ One entry per source drawn from: authorization-server metadata (endpoints, grant types, S256, `client_secret_post`, no `registration_endpoint`). - `doctrine/speakeasy-setup.md` — observed - `2026-07-28T18:22:41Z`. Backs the catalog add-server and manual OAuth + `2026-08-11T15:40:29Z`. Backs the catalog add-server and manual OAuth attachment labels, fixed Speakeasy anchors, and closing pointer. diff --git a/retro/runs/2026-08-11T15:40:29Z-hubspot.json b/retro/runs/2026-08-11T15:40:29Z-hubspot.json new file mode 100644 index 0000000..e0b32b8 --- /dev/null +++ b/retro/runs/2026-08-11T15:40:29Z-hubspot.json @@ -0,0 +1,79 @@ +{ + "slug": "hubspot", + "provider": "hubspot", + "persona": "it-admin", + "timestamp": "2026-08-11T15:40:29Z", + "started_at": "2026-08-11T15:40:29Z", + "finished_at": "2026-08-11T15:43:32Z", + "runtime": "pi", + "status": "awaiting_scope", + "failed_phase": "scope", + "notes": "Updated research.md and meta.yaml in guides/hubspot/ using the 2026-08-11T15:40:29Z observation timestamp. Preserved stable anchors and existing verified work. Reverified HubSpot’s primary setup page, documentation index, permissions guide, changelog pages, OAuth metadata endpoints, and live 401 discovery behavior. Added newly documented conversation and marketing-email access details and updated the Sensitive Data restriction to include conversation data. Retained manual OAuth registration, PKCE, shared streamable-HTTP remote, and provider-steps. Forced the catalog-only add-server path for com.pulsemcp.mirror/hubspot as directed. Validated meta.yaml successfully against schema/guide.v1.schema.json with Python jsonschema Draft7Validator and FormatChecker; ajv-cli could not load the schema because its date-time format support was unavailable.", + "open_questions": [ + "The overview page's new HubSpot Developer Platform prerequisite conflicts with the setup page and GA announcement, which say the server is available to all HubSpot accounts." + ], + "scope": { + "pause": true, + "material": [ + { + "index": 1, + "question": "The overview page's new HubSpot Developer Platform prerequisite conflicts with the setup page and GA announcement, which say the server is available to all HubSpot accounts.", + "why_material": "Conflicting or mutually exclusive setup paths — pick one before drafting." + } + ], + "soft": [ + "Which HubSpot permission gates the Development workspace and MCP Auth Apps remains undocumented; Developer tools access is only a flagged inference.", + "The current MCP Auth Apps beta status remains ambiguous because older 2026 material labels it Public Beta while the current setup page has no beta label.", + "The admin-connects-first requirement is documented only on the partially stale overview page; the qualifying admin role and pre-admin user experience are undocumented.", + "HubSpot documents the end-user authorization sequence but not the current exact labels of its authorization controls.", + "**Which permission gates the Development workspace / MCP Auth Apps.**", + "**MCP Auth Apps beta status.** The MCP Auth Apps UI was announced as", + "**Admin-connects-first mechanics.** Only the overview page states the", + "**\"New HubSpot Developer Platform\" prerequisite.** The overview page", + "**End-user authorization control labels.** HubSpot documents that the" + ], + "unanswered": [ + { + "index": 1, + "question": "The overview page's new HubSpot Developer Platform prerequisite conflicts with the setup page and GA announcement, which say the server is available to all HubSpot accounts.", + "why_material": "Conflicting or mutually exclusive setup paths — pick one before drafting." + } + ] + }, + "research_change": { + "method": "judge", + "unchanged": false, + "notes": "AFTER adds a draft-relevant Sensitive Data restriction: conversation data is now blocked alongside activity objects when Sensitive Data is enabled, and clarifies that this restriction is MCP-specific. This requires re-rendering the existing gotcha in external.md and invalidates review of the prior wording. HubSpot also newly documents conversation and marketing-email access, though those capability-inventory additions are less relevant to first-connect setup. Anchors, credentials, remote URL, transport, prerequisites, catalog path, and meta.yaml facts are otherwise unchanged apart from observed_at churn." + }, + "notes_digest": "sha256:59d2aee69ef72522bb6c5833f05be51c6055d6b666fea1d33a86682777c9456a", + "history": [ + { + "phase": "scope_gate", + "material": [ + { + "index": 1, + "question": "The overview page's new HubSpot Developer Platform prerequisite conflicts with the setup page and GA announcement, which say the server is available to all HubSpot accounts.", + "why_material": "Conflicting or mutually exclusive setup paths — pick one before drafting." + } + ], + "soft": [ + "Which HubSpot permission gates the Development workspace and MCP Auth Apps remains undocumented; Developer tools access is only a flagged inference.", + "The current MCP Auth Apps beta status remains ambiguous because older 2026 material labels it Public Beta while the current setup page has no beta label.", + "The admin-connects-first requirement is documented only on the partially stale overview page; the qualifying admin role and pre-admin user experience are undocumented.", + "HubSpot documents the end-user authorization sequence but not the current exact labels of its authorization controls.", + "**Which permission gates the Development workspace / MCP Auth Apps.**", + "**MCP Auth Apps beta status.** The MCP Auth Apps UI was announced as", + "**Admin-connects-first mechanics.** Only the overview page states the", + "**\"New HubSpot Developer Platform\" prerequisite.** The overview page", + "**End-user authorization control labels.** HubSpot documents that the" + ], + "unanswered": [ + { + "index": 1, + "question": "The overview page's new HubSpot Developer Platform prerequisite conflicts with the setup page and GA announcement, which say the server is available to all HubSpot accounts.", + "why_material": "Conflicting or mutually exclusive setup paths — pick one before drafting." + } + ] + } + ] +}