docs(hubspot): optional scopes, app type guidance, and MCP connector sync

src/components/templates/agent-connectors/_section-after-authentication-hubspot-app-types.mdx

@@ -0,0 +1,21 @@
+import { Aside } from '@astrojs/starlight/components'
+
+export const sectionTitle = 'Choosing a HubSpot app type'
+
+HubSpot has three app shapes. The shape you choose determines which OAuth flow, scope format, and Scalekit configuration apply.
+
+| App type | OAuth redirect | Scope format | Use with Scalekit |
+| --- | --- | --- | --- |
+| Public app | Supported | Modern (`crm.objects.contacts.read`) | Recommended |
+| Private app | Not supported | N/A — static API token only | Not supported |
+| Legacy / developer-account app | Supported | Bare strings (`contacts`, `automation`) | Supported — enter bare strings in **Permissions** |
+
+**Public apps** are the standard choice for production integrations. They support the OAuth redirect flow that Scalekit manages, and they use the modern dotted scope format.
+
+**Private apps** issue static API tokens and have no OAuth redirect endpoint. Scalekit's HubSpot connector requires an OAuth flow, so Private apps are not compatible.
+
+**Legacy apps** (older apps created in HubSpot developer test accounts before the current console) still support OAuth but use an older scope vocabulary. If you already have a legacy app, you can connect it — you just need to enter the older bare scope strings exactly as HubSpot lists them in that app's **Auth** > **Scopes** page.
+
+<Aside type="caution" title="Legacy app scope strings">
+  Legacy HubSpot apps reject the modern `crm.objects.*` format. Copy scope strings from your app's **Auth** > **Scopes** screen in HubSpot and paste them into Scalekit's **Permissions** field as-is.
+</Aside>

src/components/templates/agent-connectors/_section-before-tool-list-googledwd-common-workflows.mdx

@@ -1,4 +1,4 @@
-export const sectionTitle = 'Common workflows'
+export const sectionTitle = 'Execute tools'
 
 import { Tabs, TabItem } from '@astrojs/starlight/components'
 

src/components/templates/agent-connectors/_section-before-tool-list-hubspot-optional-scopes.mdx

@@ -0,0 +1,53 @@
+import { Aside } from '@astrojs/starlight/components'
+
+export const sectionTitle = 'Required and optional scopes'
+
+HubSpot's OAuth connection requires one scope and supports up to 23 optional scopes. Grant only the scopes your tools actually need — a smaller scope set means a simpler consent screen and a faster app review for public listings.
+
+### Required scope
+
+`oauth` — included automatically on every HubSpot connection. You do not need to add it manually.
+
+### Optional scopes
+
+Add scopes that match the tools you plan to call. Common choices:
+
+| Scope | Enables |
+| --- | --- |
+| `crm.objects.contacts.read` | Read contacts |
+| `crm.objects.contacts.write` | Create and update contacts |
+| `crm.objects.companies.read` | Read companies |
+| `crm.objects.companies.write` | Create and update companies |
+| `crm.objects.deals.read` | Read deals |
+| `crm.objects.deals.write` | Create and update deals |
+| `crm.objects.line_items.read` | Read line items |
+| `crm.objects.line_items.write` | Create and update line items |
+| `crm.objects.quotes.read` | Read quotes |
+| `crm.lists.read` | Read contact lists |
+| `crm.lists.write` | Create and manage contact lists |
+| `tickets` | Read and write support tickets |
+| `forms` | Read forms and form submissions |
+| `automation` | Read and trigger workflows and engagements |
+| `e-commerce` | Products and orders |
+
+See HubSpot's [scope reference](https://developers.hubspot.com/docs/api/working-with-oauth#scopes) for the full list.
+
+### Configure optional scopes in your HubSpot app
+
+In your HubSpot app, go to **Auth** > **Auth settings** > **Scopes**. You'll see three categories: **Required scopes** (always requested), **Conditionally required scopes**, and **Optional scopes** (requested only when the user's account has access to them).
+
+![HubSpot Scopes page showing Required, Conditionally required, and Optional scopes sections](@/assets/docs/agent-connectors/hubspot/optional-scopes.png)
+
+Click **Add new scope** and select the optional scopes your app needs. Optional scopes let users without access to a feature still install your app — HubSpot simply skips those scopes at consent time.
+
+### Enable the same optional scopes in Scalekit
+
+![Selecting optional scopes in Scalekit](@/assets/docs/agent-connectors/hubspot/add-scopes.gif)
+
+1. Open the connection in **AgentKit** > **Connections**.
+2. In the **Permissions** field, enter the scopes you need, space-separated. Example for a read-only CRM flow: `crm.objects.contacts.read crm.objects.companies.read crm.objects.deals.read`.
+3. Make sure the scope set here matches exactly what you've configured in your HubSpot app. A mismatch causes an `invalid_scope` error when the user authorizes.
+
+<Aside type="tip" title="Keep scope sets aligned">
+  Your Scalekit connection, your HubSpot app, and any SDK calls must use the same scope set. The safest workflow: configure scopes in your HubSpot app first, then copy them into Scalekit's **Permissions** field.
+</Aside>

src/components/templates/agent-connectors/_setup-hubspot.mdx

@@ -9,20 +9,22 @@ Register your Scalekit environment with the HubSpot connector so Scalekit handle
 
       ![Copy redirect URI from Scalekit dashboard](@/assets/docs/agent-connectors/hubspot/use-own-credentials-redirect-uri.png)
 
-    - Log in to your [HubSpot developer dashboard](https://developers.hubspot.com/), click **Manage apps**, click **Create app**, and select **Public app**. Do not select **Private app**; Private Apps use static API tokens and do not support OAuth redirect flows, so they do not show the Redirect URL field Scalekit needs. If you already have a HubSpot Public App, open that app instead.
+    - Log in to your [HubSpot developer dashboard](https://developers.hubspot.com/), click **Manage apps**, click **Create app**, and select **Public app**. If you already have an existing HubSpot app, open that app instead — see the **Choosing a HubSpot app type** section above for guidance on Public, Private, and legacy apps.
 
     - Go to **Auth** > **Auth settings** > **Redirect URL**, paste the redirect URI from Scalekit, and click **Save**.
 
       ![Adding redirect URL to HubSpot](@/assets/docs/agent-connectors/hubspot/add-redirect-url.png)
 
-    - Under **Auth** > **Auth settings** > **Scopes**, select the required scopes for your application. The scopes you select here must match exactly what you configure in Scalekit. For a read-only CRM enrichment flow that looks up contacts, companies, and deals, use:
+    - Under **Auth** > **Auth settings** > **Scopes**, select the scopes your application needs. The scopes you select here must match exactly what you configure in Scalekit. For a read-only CRM enrichment flow, start with:
 
       ```text
       crm.objects.contacts.read
       crm.objects.companies.read
       crm.objects.deals.read
       ```
 
+      These assume a modern Public app with dotted scope names. For legacy apps or the full scope reference, see the **Required and optional scopes** section on this page.
+
 2. ### Get client credentials
 
     - In your HubSpot app, go to **Auth** > **Auth settings**.
@@ -36,7 +38,7 @@ Register your Scalekit environment with the HubSpot connector so Scalekit handle
     - Enter your credentials:
       - **Client ID** (from your HubSpot app)
       - **Client Secret** (from your HubSpot app)
-      - **Permissions** (OAuth scope strings such as `crm.objects.contacts.read`, entered exactly as configured in the HubSpot app)
+      - **Permissions** (OAuth scope strings such as `crm.objects.contacts.read`, entered exactly as configured in the HubSpot app). For a full list of available scopes and guidance on optional scopes, see the **Required and optional scopes** section on this page.
 
       ![Add credentials in Scalekit dashboard](@/assets/docs/agent-connectors/hubspot/add-credentials.png)
 

src/components/templates/agent-connectors/index.ts

@@ -25,13 +25,12 @@ export { default as SetupDiscordSection } from './_setup-discord.mdx'
 export { default as SetupDropboxSection } from './_setup-dropbox.mdx'
 export { default as SetupExaSection } from './_setup-exa.mdx'
 export { default as SetupFellowaimcpSection } from './_setup-fellowaimcp.mdx'
-export { default as SetupFirecrawlmcpSection } from './_setup-firecrawlmcp.mdx'
 export { default as SetupFigmaSection } from './_setup-figma.mdx'
+export { default as SetupFirecrawlmcpSection } from './_setup-firecrawlmcp.mdx'
 export { default as SetupGithubSection } from './_setup-github.mdx'
 export { default as SetupGitlabSection } from './_setup-gitlab.mdx'
 export { default as SetupGmailSection } from './_setup-gmail.mdx'
 export { default as SetupGongSection } from './_setup-gong.mdx'
-export { default as SetupGrainmcpSection } from './_setup-grainmcp.mdx'
 export { default as SetupGoogleAdsSection } from './_setup-google-ads.mdx'
 export { default as SetupGoogleDocsSection } from './_setup-google-docs.mdx'
 export { default as SetupGoogleDriveSection } from './_setup-google-drive.mdx'
@@ -41,6 +40,7 @@ export { default as SetupGoogleSheetsSection } from './_setup-google-sheets.mdx'
 export { default as SetupGooglecalendarSection } from './_setup-googlecalendar.mdx'
 export { default as SetupGoogledwdSection } from './_setup-googledwd.mdx'
 export { default as SetupGoogleslidesSection } from './_setup-googleslides.mdx'
+export { default as SetupGrainmcpSection } from './_setup-grainmcp.mdx'
 export { default as SetupHarvestapiSection } from './_setup-harvestapi.mdx'
 export { default as SetupHeyreachSection } from './_setup-heyreach.mdx'
 export { default as SetupHubspotSection } from './_setup-hubspot.mdx'
@@ -80,6 +80,7 @@ export { default as SetupZendeskSection } from './_setup-zendesk.mdx'
 export { default as SetupZoomSection } from './_setup-zoom.mdx'
 export { default as ConnectedAccountBigqueryserviceaccountSection } from './_connected-account-bigqueryserviceaccount.mdx'
 export { default as SectionAfterAuthenticationGoogledwdAuth } from './_section-after-authentication-googledwd-auth.mdx'
+export { default as SectionAfterAuthenticationHubspotAppTypes } from './_section-after-authentication-hubspot-app-types.mdx'
 export { default as SectionAfterSetupAdobemarketingagentmcpCommonWorkflows } from './_section-after-setup-adobemarketingagentmcp-common-workflows.mdx'
 export { default as SectionAfterSetupAdzvisermcpCommonWorkflows } from './_section-after-setup-adzvisermcp-common-workflows.mdx'
 export { default as SectionAfterSetupAirtableCommonWorkflows } from './_section-after-setup-airtable-common-workflows.mdx'
@@ -111,8 +112,8 @@ export { default as SectionAfterSetupDropboxCommonWorkflows } from './_section-a
 export { default as SectionAfterSetupExaCommonWorkflows } from './_section-after-setup-exa-common-workflows.mdx'
 export { default as SectionAfterSetupFathomCommonWorkflows } from './_section-after-setup-fathom-common-workflows.mdx'
 export { default as SectionAfterSetupFellowaimcpCommonWorkflows } from './_section-after-setup-fellowaimcp-common-workflows.mdx'
-export { default as SectionAfterSetupFirecrawlmcpCommonWorkflows } from './_section-after-setup-firecrawlmcp-common-workflows.mdx'
 export { default as SectionAfterSetupFigmaCommonWorkflows } from './_section-after-setup-figma-common-workflows.mdx'
+export { default as SectionAfterSetupFirecrawlmcpCommonWorkflows } from './_section-after-setup-firecrawlmcp-common-workflows.mdx'
 export { default as SectionAfterSetupFreshdeskCommonWorkflows } from './_section-after-setup-freshdesk-common-workflows.mdx'
 export { default as SectionAfterSetupGithubCommonWorkflows } from './_section-after-setup-github-common-workflows.mdx'
 export { default as SectionAfterSetupGmailCommonWorkflows } from './_section-after-setup-gmail-common-workflows.mdx'
@@ -127,8 +128,8 @@ export { default as SectionAfterSetupGoogleformsCommonWorkflows } from './_secti
 export { default as SectionAfterSetupGooglemeetCommonWorkflows } from './_section-after-setup-googlemeet-common-workflows.mdx'
 export { default as SectionAfterSetupGooglesheetsCommonWorkflows } from './_section-after-setup-googlesheets-common-workflows.mdx'
 export { default as SectionAfterSetupGoogleslidesCommonWorkflows } from './_section-after-setup-googleslides-common-workflows.mdx'
-export { default as SectionAfterSetupGranolamcpCommonWorkflows } from './_section-after-setup-granolamcp-common-workflows.mdx'
 export { default as SectionAfterSetupGrainmcpCommonWorkflows } from './_section-after-setup-grainmcp-common-workflows.mdx'
+export { default as SectionAfterSetupGranolamcpCommonWorkflows } from './_section-after-setup-granolamcp-common-workflows.mdx'
 export { default as SectionAfterSetupHarvestapiCommonWorkflows } from './_section-after-setup-harvestapi-common-workflows.mdx'
 export { default as SectionAfterSetupHeyreachCommonWorkflows } from './_section-after-setup-heyreach-common-workflows.mdx'
 export { default as SectionAfterSetupHubspotCommonWorkflows } from './_section-after-setup-hubspot-common-workflows.mdx'
@@ -169,6 +170,7 @@ export { default as SectionAfterSetupZoomCommonWorkflows } from './_section-afte
 export { default as SectionAfterToolListSalesforceMetadataApiSoap } from './_section-after-tool-list-salesforce-metadata-api-soap.mdx'
 export { default as SectionBeforeToolListDatadogResourceIds } from './_section-before-tool-list-datadog-resource-ids.mdx'
 export { default as SectionBeforeToolListGoogledwdCommonWorkflows } from './_section-before-tool-list-googledwd-common-workflows.mdx'
+export { default as SectionBeforeToolListHubspotOptionalScopes } from './_section-before-tool-list-hubspot-optional-scopes.mdx'
 export { default as SectionBeforeToolListHubspotResourceIds } from './_section-before-tool-list-hubspot-resource-ids.mdx'
 export { default as SectionBeforeToolListLinearResourceIds } from './_section-before-tool-list-linear-resource-ids.mdx'
 export { default as SectionBeforeToolListMondayResourceIds } from './_section-before-tool-list-monday-resource-ids.mdx'

src/content/docs/agentkit/connectors/adzvisermcp.mdx

@@ -23,7 +23,9 @@ import ToolList from '@/components/ToolList.astro'
 import { tools } from '@/data/agent-connectors/adzvisermcp'
 import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'
 import { AgentKitCredentials } from '@components/templates'
+import { SetupAdzvisermcpSection } from '@components/templates'
 import { QuickstartGenericOauthSection } from '@components/templates'
+import { SectionAfterSetupAdzvisermcpCommonWorkflows } from '@components/templates'
 
 <Steps>
 
@@ -48,7 +50,18 @@ import { QuickstartGenericOauthSection } from '@components/templates'
 
    <AgentKitCredentials />
 
-3. ### Authorize and make your first call
+3. ### Set up the connector
+
+   Register your Adzviser MCP credentials with Scalekit so it handles the token lifecycle. You do this once per environment.
+
+   <details>
+   <summary>Dashboard setup steps</summary>
+
+   <SetupAdzvisermcpSection />
+
+   </details>
+
+4. ### Authorize and make your first call
 
    <QuickstartGenericOauthSection connector="adzvisermcp" toolName="adzvisermcp_list_metrics_and_breakdowns_activecampaign" providerName="Adzviser MCP" />
 
@@ -61,6 +74,10 @@ Connect this agent connector to let your agent:
 - **Data retrieve reporting** — Retrieve real-time reporting data from marketing channels like Google Ads, Facebook Ads and Google Analytics
 - **List workspace, metrics fb page, metrics and breakdowns zoho** — Retrieve a list of workspaces that have been created by the user and their data sources, such as Google Ads, Facebook Ads accounts connected with each
 
+## Common workflows
+
+<SectionAfterSetupAdzvisermcpCommonWorkflows />
+
 ## Tool list
 
 Use the exact tool names from the **Tool list** below when you call `execute_tool`. If you're not sure which name to use, list the tools available for the current user first.

src/content/docs/agentkit/connectors/commonroommcp.mdx

@@ -23,7 +23,9 @@ import ToolList from '@/components/ToolList.astro'
 import { tools } from '@/data/agent-connectors/commonroommcp'
 import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'
 import { AgentKitCredentials } from '@components/templates'
+import { SetupCommonroommcpSection } from '@components/templates'
 import { QuickstartGenericOauthSection } from '@components/templates'
+import { SectionAfterSetupCommonroommcpCommonWorkflows } from '@components/templates'
 
 <Steps>
 
@@ -48,7 +50,18 @@ import { QuickstartGenericOauthSection } from '@components/templates'
 
    <AgentKitCredentials />
 
-3. ### Authorize and make your first call
+3. ### Set up the connector
+
+   Register your Commonroom MCP credentials with Scalekit so it handles the token lifecycle. You do this once per environment.
+
+   <details>
+   <summary>Dashboard setup steps</summary>
+
+   <SetupCommonroommcpSection />
+
+   </details>
+
+4. ### Authorize and make your first call
 
    <QuickstartGenericOauthSection connector="commonroommcp" toolName="commonroommcp_commonroom_get_catalog" providerName="Commonroom MCP" />
 
@@ -64,6 +77,10 @@ Connect this agent connector to let your agent:
 - **Get commonroom** — Retrieve the catalog of available object types, their properties, and allowed sort fields in Common Room
 - **Create commonroom** — Create a new object in Common Room — contact, organization, activity, or custom object type
 
+## Common workflows
+
+<SectionAfterSetupCommonroommcpCommonWorkflows />
+
 ## Tool list
 
 Use the exact tool names from the **Tool list** below when you call `execute_tool`. If you're not sure which name to use, list the tools available for the current user first.

src/content/docs/agentkit/connectors/customeriomcp.mdx

@@ -23,7 +23,9 @@ import ToolList from '@/components/ToolList.astro'
 import { tools } from '@/data/agent-connectors/customeriomcp'
 import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'
 import { AgentKitCredentials } from '@components/templates'
+import { SetupCustomeriomcpSection } from '@components/templates'
 import { QuickstartGenericOauthSection } from '@components/templates'
+import { SectionAfterSetupCustomeriomcpCommonWorkflows } from '@components/templates'
 
 <Steps>
 
@@ -48,7 +50,18 @@ import { QuickstartGenericOauthSection } from '@components/templates'
 
    <AgentKitCredentials />
 
-3. ### Authorize and make your first call
+3. ### Set up the connector
+
+   Register your Customer.io MCP credentials with Scalekit so it handles the token lifecycle. You do this once per environment.
+
+   <details>
+   <summary>Dashboard setup steps</summary>
+
+   <SetupCustomeriomcpSection />
+
+   </details>
+
+4. ### Authorize and make your first call
 
    <QuickstartGenericOauthSection connector="customeriomcp" toolName="customeriomcp_cio_auth_status" providerName="Customer.io MCP" />
 
@@ -65,6 +78,10 @@ Connect this agent connector to let your agent:
 - **Prime cio** — Print LLM-ready instructions for using the Customer.io API
 - **Delete cio** — Delete a resource via the Customer.io API (DELETE only)
 
+## Common workflows
+
+<SectionAfterSetupCustomeriomcpCommonWorkflows />
+
 ## Tool list
 
 Use the exact tool names from the **Tool list** below when you call `execute_tool`. If you're not sure which name to use, list the tools available for the current user first.