HubSpot MCP: qual caminho usar, o que o servidor faz e onde ele para

HubSpot MCP: qual caminho usar, o que o servidor faz e onde ele para

O HubSpot MCP é o servidor oficial que liga assistentes de IA ao seu CRM por meio do Model Context Protocol (MCP), um padrão aberto para isso. O servidor remoto em https://mcp.hubspot.com permite que o Claude, o ChatGPT e outros clientes MCP leiam e alterem registros na sua conta do HubSpot, e ele está disponível para todas as contas do HubSpot desde 13 de abril de 2026. Se você usa o Claude ou o ChatGPT, não precisa construir nada: instale o conector pronto do HubSpot e faça login. Você só cria o seu próprio conector MCP no HubSpot quando conecta um cliente diferente.

O HubSpot também oferece um segundo servidor, sem relação com o primeiro, para desenvolvedores, que roda localmente pela CLI do HubSpot, um servidor MCP local nos termos do protocolo. A maior parte da confusão em torno do "HubSpot MCP" vem de misturar os dois, ou de misturar o servidor do HubSpot com os muitos servidores da comunidade no GitHub.

Divulgação: o Customermates, um CRM de código aberto com o seu próprio servidor MCP, publica este guia. Os detalhes do HubSpot foram verificados em 8 de outubro de 2026 nas páginas do próprio HubSpot, com links na linha de fontes no fim.

Em resumo

Servidor remoto

Hospedado pelo HubSpot em mcp.hubspot.com. Lê e grava registros do CRM, atividades e conteúdo de marketing, sempre dentro das permissões do usuário conectado no HubSpot.

Caminho mais rápido

Claude e ChatGPT: instale o conector do HubSpot e faça login com OAuth. O HubSpot diz que o conector do Claude é gratuito em todos os níveis do HubSpot.

Outros clientes

Crie um conector MCP em Development no HubSpot e use o ID do cliente e o secret em um cliente que aceite OAuth com PKCE.

Principais limites

Dados de atividades e conversas ficam bloqueados quando o Sensitive Data está ativado, o acesso de gravação documentado não inclui exclusão, e algumas ferramentas exigem hubs pagos.

O que é um servidor MCP, na prática

O MCP define como um cliente de IA, como o Claude ou o ChatGPT, chama ferramentas de outro sistema. No HubSpot, essas ferramentas buscam registros, criam notas ou listam negócios. Quando você pergunta "quais negócios estão parados na etapa Proposta?", o cliente escolhe a ferramenta de busca, o servidor a executa na sua conta, com as suas permissões, e o resultado volta para a conversa. O servidor não é um modelo de IA nem um plugin de navegador: é a ponte entre os dois. Para um panorama do protocolo, veja o que é um servidor MCP; para a diferença entre o MCP e uma API comum, MCP vs API.

Escolha primeiro o seu caminho

A pergunta "como conecto o HubSpot MCP" tem quatro respostas diferentes, conforme o cliente e a tarefa.

Servidores de terceiros são uma quinta opção. A Zapier, por exemplo, oferece ações do HubSpot pelo próprio servidor MCP em mcp.zapier.com, e o GitHub tem vários servidores do HubSpot criados pela comunidade que você mesmo executa. Eles são úteis quando você quer um servidor MCP único para muitos aplicativos. Não são o servidor do HubSpot, então o escopo, a manutenção e o tratamento de dados dependem do que o mantenedor decidir.

O que o servidor remoto pode ler e gravar

O guia de integração do HubSpot lista o acesso em detalhes. Em resumo:

Dois detalhes importam para o planejamento. O servidor é construído sobre a API de busca do CRM do HubSpot, que, segundo o HubSpot, não tem busca vetorial, então a IA encontra registros por filtros e propriedades, não por significado. E quando um registro é criado ou atualizado, o servidor aplica a lógica condicional de campos e as validações de etapa do pipeline da conta, então a IA não consegue pular um campo obrigatório que uma pessoa também não poderia pular.

Limites que o HubSpot documenta

• O Sensitive Data bloqueia atividades. Se a sua conta tem o Sensitive Data ativado, ligações, e-mails, reuniões, notas, tarefas e conversas ficam bloqueados pelo servidor MCP. O HubSpot observa que isso vale só para o MCP, não para as suas APIs padrão do CRM.
• Sem exclusão. O acesso de gravação documentado cobre criar, editar, registrar e publicar. Excluir registros não está listado, então a limpeza continua sendo um trabalho manual no HubSpot.
• As permissões são herdadas. Cada chamada roda como o usuário conectado e respeita as permissões dele no HubSpot. O acesso restrito a certos usuários ou equipes na caixa de entrada também é restrito pelo MCP.
• Os escopos são fixados na instalação. Você não escolhe os escopos. Eles vêm das ferramentas disponíveis no momento da instalação e das permissões que o usuário concede. Quando o HubSpot adiciona ferramentas, os usuários existentes precisam reinstalar para conceder os novos escopos.
• Algumas ferramentas exigem hubs pagos. As métricas de AEO e os prompts monitorados exigem Marketing Hub Professional ou Enterprise; os orçamentos exigem Revenue Hub Professional ou Enterprise.
• A análise é limitada. A ferramenta de consulta SQL aceita filtragem, agregação e ordenação, mas o HubSpot afirma que ela não tem joins, subconsultas, navegação por associações nem conversão de moeda. Perguntas como "taxa de conversão por transição de etapa no último trimestre" podem exigir várias chamadas ou um relatório criado no HubSpot.

Conecte: o caminho personalizado, passo a passo

Para o Claude e o ChatGPT, o conector cuida de tudo o que vem a seguir. Para qualquer outro cliente, o guia do HubSpot descreve estes passos:

1. Crie um conector MCP

   No HubSpot, vá em Development, depois MCP Connectors, depois Create MCP connector. Informe um nome, uma descrição opcional e a URL de redirecionamento que o seu cliente usa. Para testar com o MCP Inspector, o HubSpot pede que você adicione http://localhost:6274/oauth/callback/debug.

2. Copie as credenciais

   A página de detalhes do conector mostra o ID do cliente, o secret do cliente e as URLs de redirecionamento. A URL de redirecionamento precisa ser exatamente igual à configurada no seu cliente.

3. Aponte o cliente para o servidor

   Configure o seu cliente com https://mcp.hubspot.com e as credenciais. O cliente precisa executar o fluxo OAuth com PKCE. O MCP Inspector faz isso automaticamente; em uma integração própria, você mesmo o implementa.

4. Autorize e verifique

   Escolha a conta do HubSpot, conceda as permissões e autorize. Depois chame get_user_details: o HubSpot recomenda essa chamada para ver quais ferramentas e objetos a sua conta realmente pode usar.

Solução de problemas

O servidor MCP para desenvolvedores do HubSpot

O servidor MCP para desenvolvedores roda na sua máquina e é configurado com hs mcp setup (CLI do HubSpot 8.2.0 ou posterior). Ele funciona com Claude Code, Codex CLI, Cursor, Gemini CLI, VS Code e Windsurf e aparece neles como "HubSpotDev". O HubSpot o descreve como ferramentas para tarefas de desenvolvimento de aplicativos e de CMS. Ele não é o caminho para uma equipe de vendas que quer trabalhar com registros do CRM; isso é trabalho do servidor remoto.

Uma lista de verificação de implantação para uma equipe pequena

1. Verifique o Sensitive Data primeiro. Se estiver ativado, o MCP não enxerga atividades nem conversas, o que elimina a maioria das perguntas úteis sobre um negócio. Melhor saber antes que alguém tente.
2. Revise as permissões dos usuários no HubSpot. A IA vê exatamente o que o usuário vê. Se um usuário pode editar todos os negócios, o cliente conectado dele também pode.
3. Comece pelas leituras. Use os prompts de leitura da tabela abaixo e confira cada resposta no HubSpot.
4. Depois permita o registro. Peça uma nota em um negócio de teste e confira a nota no HubSpot depois.
5. Mantenha a publicação nas mãos de pessoas. O servidor pode publicar landing pages e posts de blog. Decida quem pode pedir isso a uma IA antes que alguém o faça por acidente.
6. Restrinja as contas onde puder. O HubSpot aponta que administradores do Claude Enterprise podem limitar o conector a contas provisionadas pela empresa, com restrições de domínio verificado.

Mais um ponto para equipes no Brasil e na UE: tudo o que o cliente de IA lê do HubSpot é processado pelo provedor de IA desse cliente. Os termos de processamento de dados do seu HubSpot não cobrem esse trecho, então confira os termos do provedor de IA e o seu próprio registro de operações de tratamento (LGPD ou GDPR, conforme o caso) antes de conectar dados de clientes. A página do HubSpot para o ChatGPT também observa que o chat no conector não está disponível, por enquanto, no plano ChatGPT Pro para usuários do EEE, da Suíça e do Reino Unido.

Exemplos de prompts para testar

Escreva o prompt como pediria a alguém da equipe: com o nome do negócio, a etapa e o período. Perguntas que dependem de joins ou de conversão de moeda podem exigir vários passos ou um relatório criado no HubSpot.

Quando o próprio CRM tem um servidor MCP

Se você está escolhendo um CRM em vez de conectar um já existente, um servidor MCP embutido no CRM é a alternativa. A Customermates é um exemplo: o endpoint em /api/v1/mcp faz parte de todos os planos na nuvem e das instalações com hospedagem própria. No Claude e no ChatGPT, você o adiciona como conector personalizado e faz login (guia de configuração); Claude Code, Codex, Cursor e Gemini CLI se conectam com uma chave de API (configuração da CLI). Um cliente conectado descobre 59 ferramentas, e você pode reduzir o conjunto com um parâmetro de URL, como descrito na referência do MCP.

Poder excluir e enviar corta para os dois lados. O servidor do Customermates diz aos clientes conectados que peçam confirmação antes de excluir ou enviar, mas isso é uma orientação ao cliente, não uma trava no servidor: quando um cliente autorizado chama uma ferramenta, ela roda. Veja como o seu cliente trata as aprovações de ferramentas e comece por leituras e rascunhos, como com o HubSpot.

O custo também funciona de outro jeito. O MCP está incluído em todos os planos, inclusive no gratuito, com um limite de requisições; os planos pagos começam em € 12 por usuário por mês, e as ferramentas da caixa de entrada exigem o Pro, a € 29. Um cliente de IA externo usa a sua própria assinatura de IA, não os créditos do Customermates. O Customermates Cloud também tem o Mate, um assistente dentro do aplicativo que usa créditos de IA hospedados, se você preferir não conectar nenhum cliente externo (documentação do Mate).

O que o seu próprio agente faz com isso é follow-up. Com LinkedIn e e-mail conectados no Customermates Cloud, a partir do Pro, as conversas com clientes ficam no registro do cliente quando os dados de contato coincidem ou você as vincula, e o Claude, o ChatGPT ou o Mate redige a resposta e o próximo passo para você revisar e enviar. Para experimentar, comece o seu teste: 14 dias de Pro, sem cartão de crédito.

O Customermates é a escolha errada se você depende das ferramentas de marketing, do help desk ou dos objetos de receita do HubSpot; ele não tem nenhum deles. Se você continua no HubSpot, use o servidor do HubSpot. Se está avaliando uma troca, a comparação com alternativas ao HubSpot cobre os prós e contras, e o guia do MCP da Salesforce explica os servidores equivalentes na Salesforce. Para ver como o servidor do HubSpot se compara aos do Pipedrive, do Attio, da Salesforce e dos provedores de e-mail, leia a classificação dos melhores servidores MCP para vendas.

Perguntas frequentes

Fontes: detalhes do HubSpot verificados em 8 de outubro de 2026 no guia de integração do servidor MCP remoto, no changelog de disponibilidade geral, no guia de configuração do MCP para desenvolvedores, na página do conector do HubSpot para o Claude, na página do conector do HubSpot para o ChatGPT, nas ferramentas de IA do HubSpot e na página do HubSpot MCP da Zapier.