401 Error with User-Level OAuth Token for mcp.hubspot.com

Developer Support APIs & Integrations
1

Hello,

I’m developing a multi-tenant chat application that integrates with HubSpot, similar to the ChatGPT connector. I’m using a Public App to handle the OAuth flow for multiple users.

I’ve successfully completed the OAuth 2.0 flow using the mcp.hubspot.com endpoints:

The Problem:

When I use this access token to initialize the MCP client for the mcp.hubspot.com server, the authentication fails with a 401 Unauthorized error with the message:

“Error POSTing to endpoint (HTTP 401): This endpoint requires a user level OAuth token”

Possible Issue:

I’ve verified access token using both the introspection endpoint (https://mcp.hubspot.com/oauth/v3/token/introspect) and the access token info endpoint (https://api.hubapi.com/oauth/v1/access-tokens/{token}). Both confirm the token is active and contains user-specific details like

user

,

user_id

,

hub_id

, and

app_id

. I did notice that within the token information, there is a nested field

“signed_access_token”: { “isUserLevel”: false }

, which is confusing.

Could anyone please clarify why this token isn’t being accepted? Is there a different scope or process required specifically for the mcp.hubspot.com service?

Thank you the help.

2

Hi @kavin_kr,

The MCP endpoint is expecting a user‑level OAuth token.

  • Re-authenticate using the standard Authorization Code OAuth flow so a human user approves the app and you receive a user-bound access token (avoid private app tokens or server-to-server).
  • Get a fresh access token and initialize your MCP client with that new token.
  • If you’re using refresh tokens, ensure you refresh the access token before it expires to prevent 401s.

Confirm the token is tied to a specific user by calling GET /oauth/v1/access-tokens/{token} and checking the returned user information. Accounts Dashboard | HubSpot

If this helps, feel free to mark it as the solution :check_mark: and give it an upvote :+1: !

3

Hi @Jigar_Thakker ,

Thanks for the reply. I followed the steps from the docs, but I’m still getting the same error. Actual values are replaced with $VALUES for brevity.

1. OAuth URL

https://app.hubspot.com/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&scope=oauth&optional_scope=$OPTIONAL_SCOPE&state=$STATE

Here is the OAuth screen for your reference.

153749i6C21E045710B7B2E.png
153749i6C21E045710B7B2E.png340×400 51.4 KB

2. Token Exchange

curl -X POST "https://api.hubapi.com/oauth/v1/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code" \ -d "code=$AUTH_CODE" \ -d "client_id=$CLIENT_ID" \ -d "client_secret=$CLIENT_SECRET" \ -d "redirect_uri=$REDIRECT_URI"

3. Verified the access token metadata

curl -X GET "https://api.hubapi.com/oauth/v1/access-tokens/$ACCESS_TOKEN" \ -H "Authorization: Bearer $ACCESS_TOKEN"

Response:

{
 "token": "...",
 "user": "...",
 "hub_domain": "...",
 "scopes": [
 "oauth",
 "crm.objects.contacts.read",
 "crm.objects.contacts.write",
 "crm.objects.companies.write",
 "crm.objects.companies.read",
 "crm.objects.deals.read",
 "crm.objects.deals.write",
 "crm.objects.owners.read"
 ],
 "signed_access_token": {
 "expiresAt": 1755802709136,
 "scopes": "...",
 "hubId": ...,
 "userId": ...,
 "appId": ...,
 "signature": "...",
 "scopeToScopeGroupPks": "...",
 "newSignature": "...",
 "hublet": "...",
 "trialScopes": "",
 "trialScopeToScopeGroupPks": "",
 "isUserLevel": false,
 "installingUserId": ...,
 "isServiceAccount": false,
 "isPrivateDistribution": false
 },
 "token_type": "access",
 "user_id": ...,
 "app_id": ...,
 "hub_id": ...,
 "is_private_distribution": false,
 "expires_in": 1798
}

4. But when I tried to initialize the MCP client with that access token, it is throwing the same error.

"Error POSTing to endpoint (HTTP 401): This endpoint requires a user level OAuth token"

Let me know if you need any other details.

4

Facing this same issue. Would love to hear an update. The docs feel lacking atm

5

Hi @elie222,
Thank you for posting to the Community!
Were you able to test out @Jigar_Thakker’s Accepted Solution above? If so, where are you getting stuck? Can you share the steps you’ve taken thus far?
Thank you!
Cassie, Community Manager

6

the solution still doesn’t work for me and this post from @kavin_kr is exactly what I got. the `signed_access_token.isUserLevel` is false. no matter using token endpoint https://api.hubapi.com/oauth/v1/token or https://mcp.hubspot.com/oauth/v3/token

7

figured it out with the help of support assistant: hubhelp@hubspot.com

The problem is about the application itself created via `hs project upload`. it must have a file src/app/user-level-app-hsmeta.json with attribute like this: I’m using mine as example:
Notice it must have config isUserLevel equals to true

{"uid": "my-uid","type": "app","config": {"description": "Ari is your AI powered assistant","name": "Ari","distribution": "marketplace","isUserLevel": true,"auth": {"type": "oauth","redirectUrls": ["http://localhost:4000/oauth2/hubspot-callback","https://api-dev.ari.ariso.ai/oauth2/hubspot-callback","https://api.ari.ariso.ai/oauth2/hubspot-callback"],"requiredScopes": ["oauth","crm.objects.contacts.read","crm.objects.companies.read","crm.objects.deals.read"],"optionalScopes": ["crm.objects.products.read","crm.objects.orders.read","crm.objects.line_items.read"],"conditionallyRequiredScopes": []},"permittedUrls": {"fetch": ["https://api.hubapi.com"],"iframe": [],"img": []},"support": {"supportEmail": "support@ariso.ai","documentationUrl": "https://example.com/docs","supportUrl": "https://example.com/support","supportPhone": "+18005555555"}}}

8

Hi, is the https://mcp.hubspot.com endpoint open to any client? Would love to have read some docs about it.

9

@keurcien There isn’t any documentation available for it yet. I came across it through their blog and decided to test it out - Unlocking Deep Research for 250,000+ Businesses: How HubSpot Used MCP to Engineer the First Third-Party CRM Connector for ChatGPT.
I’m hoping it will be available for public apps as well, so we don’t need to handle granular token access ourselves and can rely on the built-in permission model instead.

10

Hi @kavin_kr

We don’t have a general-use MCP connector available yet. We will keep you posted when we do release it. I’m curious to learn what type of multi-tenant chat application you are building and what use cases would it solve for.

11

Hi @sejal_parikh ,

I’m building a centralized AI hub for enterprises where they can interact with different models using their enterprise data.

  1. Do you have plans to support public use? If so, any ETA would be helpful.
  2. If there are no plans yet, our use case is very similar to your existing ChatGPT connector. Could you provide a special setup similar to what you did for ChatGPT?
  3. If neither of the above is possible, could you provide some guidance on setting up a connector on top of the existing architecture?

Additional context:

  • The app needs to be public so that multi-user OAuth is possible.
  • How should we manage user permissions? The access token reflects the permissions granted at the time of initialization, but if a user’s permissions are later revoked, the token may still allow access. This creates a risk of resources being accessed through the AI even though the user no longer has access. Any guidance on how to properly validate user access would be very helpful.

Thanks

12

Hi, I went through the docs Integrate AI tools with the HubSpot MCP server - HubSpot docs here as well, implemented the oauth server but when I try to initialize MCP client, same error:
> This endpoint requires a user level OAuth token
My scopes: crm.objects.contacts.write, oauth, crm.objects.companies.read, crm.objects.contacts.read

13

For those who are still facing this issue, follow the steps in the repo for the HubSpot Remote MCP integration - GitHub - hubspotdev/user-level-app-template · GitHub

14

Hey everyone, we launched beta for the remote MCP server at INBOUND. Here’s the latest landing page on that HubSpot MCP Server