HubSpot is a CRM platform for contacts, companies, deals, tickets, and marketing data. Use a public OAuth app for user-delegated access, or a private-app access token for a single controlled account.
This guide prepares HubSpot for any compatible MCP client. The HubSpot agent template is separate from the HubSpot app and authorization setup.
Choose a connection method
Choose a public OAuth app when access should follow the authorizing HubSpot user. Choose a private-app access token only for a single portal's non-interactive automation. HubSpot documents OAuth apps and private apps separately.
Recommended: Public OAuth app
OAuth is the preferred path for a user-delegated HubSpot connection. Start with a developer test account or a portal containing test CRM records, and authorize a user with only the necessary CRM permissions.
- Create a public app in the HubSpot developer account.
- Add the client redirect URI exactly as supplied by the MCP client; for Dome, enter
https://api.domesystems.ai/oauth/callback. - Select the narrowest OAuth scopes for the objects the server must read. Do not add marketing, billing, or write scopes to a read-only CRM use case.
- Start OAuth from the MCP client and authorize the test user in the intended HubSpot account.
- Read a known test contact or company and verify that a restricted object or another portal is unavailable.
Alternative: Private-app access token
Use a private app only for a non-interactive, portal-owned automation. Assign only the required scopes, store the token in secret storage, and give it a named owner and rotation plan. A private-app token is not appropriate for per-user access.
- Open the vendor's credential documentation as the dedicated least-privileged identity.
- Create a named credential for the intended test workspace, project, organization, or account—never reuse an owner or administrator credential.
- Select the minimum scopes, repositories, projects, or resources the MCP server needs; begin read-only whenever the product supports it.
- Copy the secret once into the MCP client's secret store, record its owner and rotation date, then test both an allowed record and a denied boundary.
Verify HubSpot MCP
Use this checklist to confirm the MCP server is connected with the intended access.
- Connect the MCP client using the newly created authorization.
- Confirm that HubSpot MCP tools are discovered.
- Read one known test resource that the authorized identity is allowed to access.
- Attempt to read a resource outside the approved HubSpot boundary; it should be unavailable or denied.
- Confirm that no write capability beyond the reviewed setup is available.
Troubleshooting
If installation is blocked, a HubSpot super admin may need to approve the requested scopes or app. If the server sees no records, verify the authorizing user's CRM permissions and portal selection before broadening scopes.
Next steps
Deploy the HubSpot agent template to create a governed agent in Dome that can work with the approved CRM records, with the template's included model, tools, and rules.
