# HubSpot MCP OAuth Setup

**Last Updated:** 2026-03-29

Step-by-step guide to set up the HubSpot MCP server with OAuth in Cursor. The HubSpot MCP provides read-only access to CRM data (contacts, companies, deals, tickets, etc.) for AI-assisted queries and debugging.

## Reinstall after removal (checklist)

Use this if you removed HubSpot from MCP and want it back, or cloned the repo on a new machine.

| Step | Action |
|------|--------|
| 1 | Ensure `.cursor/mcp.json` includes `"hubspot": { "url": "https://mcp.hubspot.com" }` (copy from [`.cursor/mcp.json.example`](../../.cursor/mcp.json.example) or merge that block into your existing `mcpServers`). **Do not commit** `mcp.json`. |
| 2 | Optionally run `python3 v2/scripts/dev-helpers/setup-mcp-config.py [--env-file .env]` to regenerate from the example—**merge** any custom servers or keys afterward so nothing is lost. |
| 3 | **Restart Cursor** so MCP servers reload. |
| 4 | In HubSpot: **Settings → Integrations → Developer Platform → MCP Auth Apps** — create or reuse an app; add redirect URLs (see Step 1 below), including `http://localhost:6274/oauth/callback/debug` for [MCP Inspector](https://github.com/modelcontextprotocol/inspector). |
| 5 | In Cursor: **Settings → Tools & MCP** → HubSpot → **Needs login** / **Open** → complete OAuth in the browser. |
| 6 | **Verify:** In chat, ask to query HubSpot (e.g. user details / a test contact). If you see **DCR** errors (below), use MCP Inspector to validate credentials, and use **PHP scripts + Private App token** for bulk work—see [MCP_INTEGRATION.md](MCP_INTEGRATION.md) § HubSpot. |

## Known Limitation: Cursor + HubSpot Incompatibility

**Error:** `Incompatible auth server: does not support dynamic client registration`

**Cause:** Cursor expects OAuth servers to support **Dynamic Client Registration (DCR)**—where the client auto-registers and gets a client ID. HubSpot's MCP server requires a **pre-registered MCP Auth App** (Client ID + Secret) and does not support DCR. Cursor does not currently offer a way to pass static OAuth credentials for URL-based MCPs.

**Impact:** HubSpot MCP may not complete OAuth in Cursor until either:
- Cursor adds support for static client ID/secret (see [Cursor forum](https://forum.cursor.com/t/custom-mcp-client-no-option-to-disable-dynamic-client-registration-dcr-and-use-static-mcp-client-id-in-cursor-ide/110638)), or
- HubSpot adds DCR support to their MCP auth server

**Re-check periodically:** Cursor release notes and the forum thread above—if static OAuth or HubSpot-specific support ships, retry Steps 3–6 in [Reinstall after removal](#reinstall-after-removal-checklist) and update this doc.

**Workarounds:**
1. **Use direct HubSpot API** – Production writes and debugging can use `v2/helpers/hubspot-affiliate-api.php`, scripts, and HubSpot API directly.
2. **Use MCP Inspector** – Test HubSpot MCP with [MCP Inspector](https://github.com/modelcontextprotocol/inspector) (supports manual Client ID/Secret). Add redirect `http://localhost:6274/oauth/callback/debug` to your MCP Auth App.
3. **Disable HubSpot MCP** – Remove or disable in Settings → MCP to avoid repeated connection errors.

## Prerequisites

- HubSpot account with access to the **Developer Platform** (new platform, not legacy)
- Cursor IDE (Desktop)
- Project already has `hubspot` in `.cursor/mcp.json` with `"url": "https://mcp.hubspot.com"`

## Step 1: Create MCP Auth App in HubSpot

1. Log in to your HubSpot account
2. Go to **Settings** (gear icon) → **Integrations** → **Developer Platform**
3. In the left sidebar, click **MCP Auth Apps**
4. Click **Create MCP auth app** (upper right)
5. Fill in the app details:
   - **App name**: e.g. `Ordio Cursor MCP` or `Cursor HubSpot Integration`
   - **Description**: Optional (e.g. "MCP integration for Cursor IDE")
   - **Redirect URL**: Add one or more of:
     - Cursor (from logs): `cursor://anysphere.cursor-mcp/oauth/callback` — *Note: Cursor currently fails with HubSpot due to DCR incompatibility; adding this won't fix it until Cursor supports static credentials.*
     - For MCP Inspector testing: `http://localhost:6274/oauth/callback/debug`
   - **Icon**: Optional
6. Click **Create**
7. On the app details page, note your **Client ID** and **Client secret** (you'll need these if Cursor requires manual OAuth config)

## Step 2: Configure Cursor MCP

Your `.cursor/mcp.json` should already include:

```json
{
  "mcpServers": {
    "hubspot": {
      "url": "https://mcp.hubspot.com"
    }
  }
}
```

**Optional:** If Cursor supports passing OAuth credentials for HubSpot (check Cursor docs or MCP settings), you can add:

```json
{
  "mcpServers": {
    "hubspot": {
      "url": "https://mcp.hubspot.com",
      "env": {
        "HUBSPOT_CLIENT_ID": "your-client-id",
        "HUBSPOT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

**Security:** Never commit `mcp.json` with real credentials. It's in `.gitignore`. Use `mcp.json.example` as a template without secrets.

## Step 3: Complete OAuth in Cursor

1. Restart Cursor to load the MCP config
2. Open **Settings** (gear icon) → **Tools & MCP** (or **Tools** on Free plan)
3. Under **MCP Tools**, find **HubSpot**
4. Click **Needs login** (or **Open** if it shows that)
5. In the dialog, click **Open** to launch the OAuth consent screen
6. In the browser:
   - Select the HubSpot account to connect
   - Grant the requested permissions (read-only CRM access)
   - Click **Allow** / **Authorize**
7. You'll be redirected back to Cursor—click **Open Cursor** if prompted
8. Approve the URI opening request if your OS asks

## Step 4: Verify Connection

In Cursor Chat, try:

- "Query HubSpot for the latest contacts"
- "List recent deals from HubSpot"
- "Get user details from HubSpot"

If OAuth succeeded, the HubSpot MCP tools will return data. If you see 401 or auth errors, re-check the MCP Auth App redirect URL and retry the OAuth flow.

## Redirect URL Troubleshooting

If OAuth fails with a redirect error:

1. **Check the error message** – It may show the redirect URI Cursor attempted to use
2. **Add that URI** to your MCP Auth App in HubSpot (Edit info → Redirect URLs)
3. **Common redirects** to try adding:
   - `https://cursor.com/oauth/callback`
   - `cursor://oauth/callback`
   - `http://localhost:*` (if Cursor uses a local callback)
4. **Test with MCP Inspector** – Use `http://localhost:6274/oauth/callback/debug` to verify your Client ID/Secret work, then add Cursor's redirect once you know it

## Supported Data (Read-Only)

The HubSpot MCP server provides read-only access to:

- Contacts, companies, deals, tickets
- Carts, products, orders, line items
- Invoices, quotes, subscriptions
- User details

Scopes are determined by the MCP server's tools and the permissions you grant during installation. Production writes (affiliate sync, lead capture) use the direct API—see `v2/helpers/hubspot-affiliate-api.php` and `docs/development/MCP_INTEGRATION.md`.

## References

- [HubSpot MCP Integration Docs](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server)
- [HubSpot MCP Server](https://developers.hubspot.com/mcp)
- [MCP OAuth Spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
- Project: `.cursor/README-MCP.md`, `docs/development/MCP_INTEGRATION.md`