HubSpot MCP Setup: Create a PKCE App and Protect CRM Writes
Use HubSpot's remote CRM MCP server only after you create an MCP Auth App, register the client's exact redirect URL, and use a PKCE-capable client. Start with contact or company reads, confirm the installing user's permissions and granted scopes, and add deal, engagement, or other CRM writes only after the read path works.
Use HubSpot's remote CRM MCP server only after you create an MCP Auth App, register the client's exact redirect URL, and use a PKCE-capable client. Start with contact or company reads, confirm the installing user's permissions and granted scopes, and add deal, engagement, or other CRM writes only after the read path works.
Table of contents
- Which HubSpot MCP server do you need?
- How do you create an MCP Auth App?
- How do you connect a PKCE-capable client?
- How do you verify CRM reads first?
- How do you contain deals, contacts, and engagement writes?
- How do you fix redirects, PKCE, refresh, scope, and account failures?
- FAQ
Which HubSpot MCP server do you need?
Use HubSpot's remote CRM MCP server at https://mcp.hubspot.com for CRM access from an MCP client. It is separate from HubSpot's local Developer MCP server, so identify the intended server before configuring authentication.
The remote CRM path has three practical requirements:
- An MCP Auth App in HubSpot.
- OAuth authentication with PKCE.
- A client configured with the app's client ID, client secret, and exact redirect URL.
Access follows the installing user's HubSpot permissions and the scopes granted to the app. That means a successful connection does not automatically provide unrestricted CRM access. The account, user, app scopes, and server endpoint must all align. HubSpot's remote MCP documentation distinguishes this integration from other HubSpot developer tooling.
As a practical next step, open MCPtrove's HubSpot MCP server directory entry while you collect the endpoint and client settings. Keep the remote endpoint visible during setup so it is not confused with a local developer server.
How do you create an MCP Auth App?
Create an MCP Auth App in HubSpot's developer platform, then configure its OAuth details with the exact redirect URL your client will use. Do this before starting the MCP connection.
- Open HubSpot's app-development area and create the MCP Auth App.
- Copy the app's client ID and client secret for the client configuration.
- Add the redirect URL supplied by the client, preserving it exactly.
- Select the scopes required for the intended CRM operations.
- Confirm that the HubSpot user who will install the app has the permissions needed for those operations.
The redirect URL is an exact-match value. A different path, host, port, or URL form can prevent authorization from completing, so copy the client value rather than rewriting it manually.
Use only the scopes needed for the first verification. If Sensitive Data is enabled, activity objects including calls, emails, meetings, notes, and tasks are blocked from MCP access. Account permissions and app scopes therefore need to be considered together. See HubSpot's OAuth documentation and the MCP OAuth explainer for the authorization concepts behind this setup.
How do you connect a PKCE-capable client?
Configure a PKCE-capable MCP client with https://mcp.hubspot.com, the MCP Auth App credentials, and the exact registered redirect URL. Then complete OAuth authorization using the intended HubSpot account.
Use this sequence:
- Choose a client that supports MCP authorization with PKCE.
- Add the remote CRM endpoint:
https://mcp.hubspot.com. - Enter the app's client ID and client secret.
- Enter the exact redirect URL registered in the MCP Auth App.
- Enable the client's PKCE-capable authorization flow.
- Authorize the installing user's HubSpot account.
- Return to the client and confirm that the connection is available.
For a Cursor workflow, use the Cursor client setup page as the practical configuration starting point. Do not invent a configuration format or paste credentials into a prompt when the client provides dedicated fields.
MCP authorization separates the client, authorization server, and protected resource. Keeping those roles clear helps explain why the endpoint, app registration, redirect URL, and user authorization must agree. The MCP authorization specification and MCP architecture guide provide the relevant protocol context.
How do you verify CRM reads first?
Verify the connection with a contact or company read before exposing deal, engagement, or other CRM writes. A successful read confirms that the endpoint, authorization, account, permissions, and initial scopes are aligned for at least one CRM operation.
Use a small read-first checklist:
- Confirm that the authorized user is signed in to the intended HubSpot account.
- Request a contact read.
- Request a company read.
- Check that the returned records belong to the expected account.
- Record which read worked and which scopes were granted.
- Stop and correct the connection if either read fails.
A read result should not be treated as proof that every CRM object or write is available. Deals, contacts, and engagements can be affected by different permissions, scopes, or Sensitive Data restrictions.
Before changing several settings at once, use MCPtrove's configuration validator to inspect the endpoint, credentials, redirect URL, and selected options. Then repeat one read. This creates a clear checkpoint before any write-capable configuration is introduced. HubSpot's MCP overview is the reference for the available integration context.
How do you contain deals, contacts, and engagement writes?
Contain CRM writes by starting with reads, granting only the scopes required for the next operation, and expanding one object family at a time. Keep deal, contact, and engagement changes behind an explicit authorization checkpoint.
Use this progression:
- Verify contact and company reads.
- Decide whether the workflow needs contact writes, deal writes, or engagement access.
- Add only the scopes and HubSpot permissions required for that object family.
- Test the smallest intended operation.
- Review the result before enabling another write category.
| Situation | Decision |
|---|---|
| Contact or company read | Use as the first verification step. |
| Contact write | Add only after the corresponding read works and the user has permission. |
| Deal write | Treat as a separate expansion; verify it independently. |
| Engagement access | Check Sensitive Data status first. |
| Calls, emails, meetings, notes, or tasks with Sensitive Data enabled | Expect these activity objects to be blocked from MCP access. |
This sequence limits the number of unknowns in each test. It also keeps a working read connection from being mistaken for blanket permission to modify CRM records. The MCP security best practices support keeping authorization and permission boundaries explicit.
How do you fix redirects, PKCE, refresh, scope, and account failures?
Fix failures by comparing the endpoint, exact redirect URL, PKCE capability, app credentials, authorization state, scopes, and HubSpot account permissions in that order. Keep TLS, authentication, and permission checks enabled while troubleshooting.
| Symptom | Check |
|---|---|
| Redirect error | Compare the client redirect URL with the exact URL registered in the MCP Auth App. |
| PKCE error | Confirm that the selected client supports PKCE, then start authorization again. |
| Refresh or reconnect failure | Inspect the client's authorization state and reauthorize through the configured app. |
| Scope failure | Compare the app's granted scopes with the requested CRM operation. |
| Account or permission failure | Confirm the installing user and intended HubSpot account. |
| Activity objects unavailable | Check whether Sensitive Data is enabled; listed activity objects may be blocked. |
If the client points to a local Developer MCP server, replace it with https://mcp.hubspot.com for the remote CRM integration. If the redirect is wrong, update the app or client so both values match exactly, then repeat authorization.
For a scope or account failure, do not compensate by removing permission checks. Compare the installing user's HubSpot permissions with the app's granted scopes, reduce the test to a contact or company read, and expand only after that read succeeds. The MCP authorization specification is the reference for the authorization layer.