HubSpot MCP server: setup, limits and real use cases

What the HubSpot MCP server is, and what it is not

MCP, short for Model Context Protocol, is a standard that lets an AI client call tools from another system. In this case, the other system is HubSpot. Rather than exporting a CSV, writing an API integration, or asking an assistant to guess what is in your pipeline, you can let the client request the relevant records at the time it needs them.

HubSpot's remote MCP server documentation describes it as a HubSpot-hosted endpoint for external AI tools and applications. The endpoint is https://mcp.hubspot.com. It is for work inside a HubSpot account: reading records, analyzing activity, and, when the user has permission, creating or updating records.

The Developer MCP server is local and CLI-based. It helps an IDE or coding agent search HubSpot documentation, scaffold a project, validate it, upload a build, or inspect logs. It does not turn a chat client into a CRM operator.

That distinction is where many setup guides stop too early. A useful setup starts by choosing the job:

The third row is complementary to HubSpot MCP, not a replacement. HubSpot is the system of record. A data MCP server can supply verified external facts to the same agent before the agent decides what belongs in the CRM.

Set up the remote HubSpot MCP server

The exact screens differ between clients. The security model should not. HubSpot uses OAuth, so the account owner authorizes access in HubSpot rather than handing credentials to the model.

For a compatible AI client, the general process in HubSpot's setup guide is:

1. Open the AI tool's settings and add an MCP server connection.
2. Enter https://mcp.hubspot.com as the server URL.
3. Sign in to HubSpot when the authorization window opens.
4. Review the requested permissions and authorize the connection only for the account you intend to use.
5. Start with a read-only question, such as a summary of deals that have had no activity in 30 days.
6. Inspect the answer against a few known records before you allow the client to prepare changes.

If you are building your own application, there is one more layer. HubSpot's integration documentation says to create an MCP connector in HubSpot, configure the client with its OAuth credentials, and use a client that supports OAuth with PKCE. PKCE is required. HubSpot's April 2026 announcement describes the account path as Development > MCP Auth Apps, where HubSpot generates the OAuth credentials for an auth app.

The practical rule is simple: use the client-managed connection when your AI tool supports it. Build an auth app only when you are building the connection yourself. Both routes should lead to an explicit authorization screen, not to a copied secret in a chat window.

What the remote server can read and write

The remote server is broader than a contact lookup. HubSpot documents read access for CRM records such as contacts, companies, deals, tickets, users, appointments, custom objects, and segments. It can also expose activity history, including calls, meetings, notes, tasks, and emails. That makes useful questions possible without assembling a report first:

• Which open deals have no next step and no activity in the last two weeks ?
• What did the last three calls say about a specific account ?
• Which companies have a customer lifecycle stage but no associated open renewal deal ?
• What patterns appear across closed-lost deals this quarter ?

For writes, use a narrower standard. HubSpot's MCP documentation says manage_crm_objects presents a proposed-changes summary and requires explicit user confirmation before it creates or updates records. That is the behavior you want from a CRM agent. Ask it to draft the update, verify the record and property, then confirm the change.

Before a more complex task, ask the server what is available. HubSpot documents get_user_details for checking which objects and tools the current user can access, and discover_hubspot_schema for finding object types and their read or write availability. For properties, use search_properties before querying or writing. These steps sound technical, but they prevent a common failure: an assistant confidently referring to a property that does not exist in this portal.

A safe operating sequence looks like this:

1. Ask the agent to explain the plan and name the records it will inspect.
2. Confirm the account and user context with get_user_details.
3. Ask for a small read-only sample before a broad search.
4. Review the property names and the criteria in plain language.
5. For a write, request a preview of every proposed change.
6. Confirm only the changes you want applied.
7. Open several changed records in HubSpot and verify the result.

This is especially important for bulk changes. Natural language is convenient, but it is not a change-management policy. A prompt such as "clean up our old contacts" leaves too much room for interpretation. A better request specifies the filter, the property, the new value, the exclusion criteria, and whether the agent may write at all.

Limits and risks to plan for

First, access follows HubSpot permissions. The general availability announcement states that existing HubSpot permissions are respected. If a user cannot edit a deal in HubSpot, connecting that user's account should not be treated as a way to edit it through an AI client.

Second, not every kind of data is exposed the same way. HubSpot's integration documentation warns that, when Sensitive Data is turned on for an account, conversation data is blocked through the MCP server. Treat this as a design constraint. Do not promise an agent it can summarize every conversation or engagement without checking the account's configuration and the current tool availability.

Third, query capabilities have boundaries. For example, HubSpot documents that query_crm_data supports filtering, aggregation, and sorting, but not joins, column aliases, subqueries, association traversal, or currency conversion. A pipeline analysis that needs several objects may need multiple tool calls or a different reporting approach. That is better than asking the model to infer an answer from incomplete data.

Finally, connectivity is not the same as governance. Give the connection an owner, document its intended use cases, and revoke or reauthorize it when the role changes. In a shared CRM, a personal assistant connection should not quietly become a team-wide automation.

When the Developer MCP server is the right choice

The Developer MCP server is easy to confuse with the remote one because both are called "HubSpot MCP." Their risk profiles are different.

HubSpot's setup documentation says the Developer MCP server runs locally and can be installed through the CLI. The setup command is hs mcp setup. HubSpot also documents a standalone mode that uses npx @hubspot/cli, which is useful when a corporate machine does not allow a global npm install.

Its tools are oriented toward development. According to HubSpot's Developer MCP tools reference, a coding agent can search and fetch official documentation, create and validate projects, inspect build logs, and scaffold CMS assets. Uploading and deployment remain actions that should be explicitly requested. HubSpot's own documentation flags uploads and deployments as potentially destructive.

Use it when you need to answer a development question with official documentation, validate a HubSpot project before a release, or create a local starting point for an app. Do not use it just because you want a sales summary or a contact update. That is a remote CRM-server job.

Four real use cases, with the right guardrails

1. Pipeline review before a sales meeting

Ask the remote server for the deal, its associated company, the last activities, and the next scheduled task. Keep the request read-only. The output can be a meeting brief, but the account owner should still decide whether the next step belongs in the CRM.

2. Turn approved meeting notes into CRM updates

Provide the notes, ask the agent to identify the exact contacts, company, deal, and properties it proposes to change, then review the preview. This is a good fit for MCP because the agent can resolve records and associations. It is not a good fit for a vague request to "update everything from the call."

3. Research an account before prospecting

Use HubSpot MCP to inspect what your CRM already knows. Then use a separate, approved data source for facts that are not in the CRM, such as a verified work email or a current role. Jipup's MCP server is built for that external B2B data step, while HubSpot remains where approved information is stored and worked.

4. Build a HubSpot extension with an AI coding tool

Use Developer MCP locally. Ask it to search the official documentation first, fetch the relevant page, scaffold the project, and validate it. Keep upload and deployment as separate, explicit decisions.

FAQ

Where Jipup fits

The Jipup agent does this on your CRM continuously, on the rules you set. The Jipup MCP server →

Enzo Munoz

Co-founder of Jipup, the AI agent that keeps HubSpot CRMs clean, up to date and enriched. He works every week with RevOps and sales teams on their CRM data.