Você já tem o Claude Desktop, Claude Code ou Cursor abertos mais horas por dia do que o painel do PushEngage. Toda vez que você precisa verificar uma taxa de cliques ou enviar uma notificação, você sai da janela onde o trabalho real está acontecendo. A configuração do MCP do PushEngage fecha essa lacuna: um comando npx, um login no navegador, e as ferramentas do PushEngage ficam dentro da mesma sessão de chat que você já está usando para escrever código, depurar um fluxo de trabalho ou responder a uma pergunta da sua equipe.
Este é o guia completo de configuração: instalação, as duas variáveis de ambiente que valem a pena conhecer, o primeiro login e as três coisas específicas que quebram a conexão quando ela não funciona de primeira. Ao final, você terá uma sessão autenticada com um site selecionado, não apenas um indicador verde de "conectado".
O que você poderá fazer depois de conectado
@pushengage/mcp envia 27 ferramentas em 10 domínios, e uma vez que você esteja autenticado em um site, todas elas estarão a uma frase de distância em vez de um clique no painel. Alguns exemplos do que isso parece depois que a configuração é concluída:
- Envie uma notificação push agora, agende-a para um horário específico ou configure um envio recorrente — no fuso horário local de cada assinante, se você solicitar.
- Execute um teste A/B entre dois títulos e deixe o assistente relatar a taxa de cliques quando os resultados estiverem disponíveis.
- Crie um segmento ou um grupo de audiência a partir de uma descrição em linguagem natural em vez de uma interface de regras.
- Puxe análises como um resumo vitalício ou como uma série temporal dia a dia.
- Liste suas campanhas de gotejamento, campanhas acionadas e fluxos de trabalho para verificar o que está realmente em execução.
- Leia as configurações do seu site, a configuração do service worker e a configuração do widget de chat.
Nada disso exige que o assistente tenha sua senha do PushEngage, e nada disso exige que você saia do seu editor ou terminal. O PushEngage executa esta integração para uma base de conta de mais de 25.000 proprietários de negócios em mais de 150 países, enviando 15,2 bilhões de notificações nos últimos 30 dias. O servidor MCP fala com a mesma API de produção em que esse volume é executado, não com uma demonstração sandbox.
Antes de começar: o que você precisa
Três coisas, e você provavelmente já tem pelo menos duas delas:
- Uma conta PushEngage — gratuita ou paga, com pelo menos um site adicionado. O servidor MCP não cria um site para você; ele opera em sites que você já configurou no seu painel PushEngage.
- Node.js 18 ou mais recente — o assistente executa o servidor via
npx, que vem com o Node. Verifique comnode -vem um terminal. - Um cliente compatível com MCP — Claude Desktop, Claude Code, Cursor ou qualquer outro cliente que fale MCP via entrada/saída padrão (stdio).
Uma coisa que vale a pena afirmar claramente antes de começar a editar arquivos de configuração: @pushengage/mcp é executado localmente em sua máquina via stdio. Não há servidor remoto para apontar e nenhum URL de conector hospedado. O cliente inicia o processo, e o processo fala com a API do PushEngage em seu nome. Se um guia de configuração para uma ferramenta diferente disser para você colar um endpoint remoto, esse é um tipo diferente de servidor MCP do que este.
Configurando o servidor no Claude Desktop, Claude Code e Cursor
Sem instalação global. npx busca @pushengage/mcp sob demanda na primeira vez que seu cliente o inicia, usando o comando exato npx -y @pushengage/mcp. Você adiciona esse comando à configuração MCP do seu cliente, reinicia o cliente e o servidor aparece na sua lista de ferramentas.
Cada cliente mantém sua configuração em um local diferente.
Claude Desktop
Edite ~/Library/Application Support/Claude/claude_desktop_config.json no macOS (ou o caminho equivalente na sua plataforma):
{
"mcpServers": {
"pushengage": {
"command": "npx",
"args": ["-y", "@pushengage/mcp"]
}
}
}Reinicie o Claude Desktop. O servidor "pushengage" deve aparecer na sua lista de ferramentas.
Cursor
Edite ~/.cursor/mcp.json:
{
"mcpServers": {
"pushengage": {
"command": "npx",
"args": ["-y", "@pushengage/mcp"]
}
}
}Claude Code
Claude Code fala MCP via stdio da mesma forma que Claude Desktop e Cursor, então a mesma estrutura command/args funciona se você editar seu arquivo de configuração MCP diretamente. Se preferir não editar JSON manualmente, Claude Code também aceita servidores através de seu próprio comando CLI claude mcp add, que é um comportamento geral do Claude Code e não algo específico do PushEngage. Consulte a documentação do Claude Code para a sintaxe exata da flag se você seguir esse caminho.
Qualquer outro cliente MCP
Se o seu cliente não for um dos três acima, o requisito subjacente é o mesmo em todos os lugares: configure-o para executar npx -y @pushengage/mcp como um servidor stdio. Essa é toda a etapa de instalação, independentemente de qual cliente lê a configuração.
Nomeando a conexão e isolando tokens: PE_MCP_CLIENT_NAME e PE_MCP_CONFIG_PATH
Nenhuma configuração além da etapa de instalação é necessária. O servidor fala com a API de produção do PushEngage por padrão; duas variáveis de ambiente existem para configurações menos comuns:
| Variável de ambiente | Padrão | Propósito |
|---|---|---|
PE_MCP_CLIENT_NAME | Assistente de IA | O rótulo exibido na tela de autorização do PushEngage como o aplicativo solicitando acesso. Defina-o se quiser algo mais específico, como "Claude Desktop". |
PE_MCP_CONFIG_PATH | ~/.pushengage/mcp.json | Onde o token de acesso é armazenado. Defina isso para executar mais de uma conta PushEngage lado a lado. Deve ser um caminho absoluto — sem expansão de ~. |
A maioria das configurações de conta única nunca precisa mexer em nenhuma das variáveis. PE_MCP_CLIENT_NAME é uma conveniência cosmética, útil se você quiser que a tela de autorização diga algo mais legível do que “assistente de IA” quando for você quem está clicando em Autorizar. PE_MCP_CONFIG_PATH importa no momento em que você precisa de um segundo arquivo de token separado, que é exatamente o caso abordado a seguir.
Primeira execução: login e seleção de um site
A autenticação é baseada no navegador, então o assistente nunca vê sua senha do PushEngage. O fluxo tem três etapas, e vale a pena detalhar o que cada uma delas chama internamente:
- Peça ao assistente para fazer login. Em linguagem simples: “Faça meu login no PushEngage.” Isso invoca
pushengage_auth_login, que abre uma aba do navegador para a página de autorização do PushEngage. - Clique em Autorizar. O painel envia o token para o servidor como uma requisição POST — ele nunca aparece em uma URL, histórico do navegador ou log de acesso. O token é salvo localmente com permissões
0600, legível apenas pelo seu usuário. - Peça ao assistente para mostrar seus sites e, em seguida, escolha um. “Mostrar meus sites do PushEngage” chama
pushengage_list_sites; “Usar site 12345” chamapushengage_select_site. A seleção é lembrada entre reinicializações, e todas as ferramentas com escopo de site agem sobre ela, a menos que você passe explicitamente umsite_iddiferente.
As ferramentas envolvidas, por nome:
| Ferramenta | Propósito |
|---|---|
pushengage_auth_login | Abre o navegador para o PushEngage e armazena o token em caso de sucesso. |
pushengage_auth_status | Mostra se você está autenticado e qual site está atualmente selecionado. |
pushengage_list_sites | Lista os sites do PushEngage aos quais sua conta pode acessar. |
pushengage_select_site | Define o site atual sobre o qual as outras ferramentas atuarão. |
Depois de escolher um site, execute pushengage_auth_status (perguntar “qual é o status de autenticação do meu PushEngage” é suficiente) e confirme se ele relata uma sessão autenticada e um site selecionado antes de tentar qualquer outra coisa. Essa é a linha de chegada real para a configuração, não o momento em que o cliente mostra o servidor como conectado pela primeira vez.
Solução de problemas, por causa
A maioria dos problemas de conexão remonta a uma de três causas específicas. Diagnostique nesta ordem.
O servidor não conecta de forma alguma, e seu cliente mostra “Conexão fechada.” Isso é quase sempre um problema de PATH, não um bug no servidor. Claude Desktop, Cursor e clientes semelhantes são iniciados a partir do seu Dock ou Finder, não de um terminal, então eles nunca carregam os arquivos de inicialização do seu shell. Se o Node foi instalado através de um gerenciador de versões (nvm, fnm, volta), o cliente não consegue encontrar o npx. O processo nunca é iniciado, e você recebe um erro de conexão genérico em vez de um claro “comando não encontrado”. Execute which npx em um terminal para obter o caminho absoluto e, em seguida, aponte seu cliente diretamente para ele:
{
"mcpServers": {
"pushengage": {
"command": "/absolute/path/from/which-npx",
"args": ["-y", "@pushengage/mcp"],
"env": {
"PATH": "/absolute/folder/containing/that/npx:/usr/bin:/bin:/usr/sbin:/sbin"
}
}
}
}Reinicie o cliente após a edição. Se which npx imprimir um caminho em /usr/local/bin ou /opt/homebrew/bin, um gerenciador de versão provavelmente não é o seu problema; verifique os logs do próprio MCP do cliente para o erro real.
[AUTH_EXPIRED]. Seu token expirou. Peça ao assistente para fazer login novamente — essa é toda a correção.
[NO_SITE_SELECTED]. Você está autenticado, mas nenhum site foi escolhido ainda. Chame pushengage_list_sites, depois peça para usar um dos sites retornados, antes de tentar qualquer ferramenta com escopo de site novamente.
Mais um caso que vale a pena saber, mesmo que não seja um erro: se o navegador não abrir automaticamente, você provavelmente está em uma sessão remota ou sem interface gráfica (SSH, um contêiner). A URL de autorização é impressa no terminal que executa o servidor. Abra-a manualmente.
Executando mais de uma conta ou cliente PushEngage
Se você gerencia o PushEngage para mais de uma marca, ou é uma agência executando o MCP em várias contas de clientes, a solução é o PE_MCP_CONFIG_PATH mencionado anteriormente: registre o servidor sob dois nomes diferentes, cada um com seu próprio caminho para que os tokens não colidam.
{
"mcpServers": {
"pushengage-client-a": {
"command": "npx",
"args": ["-y", "@pushengage/mcp"],
"env": {
"PE_MCP_CONFIG_PATH": "/Users/you/.pushengage/mcp-client-a.json",
"PE_MCP_CLIENT_NAME": "Claude Desktop (Client A)"
}
},
"pushengage-client-b": {
"command": "npx",
"args": ["-y", "@pushengage/mcp"],
"env": {
"PE_MCP_CONFIG_PATH": "/Users/you/.pushengage/mcp-client-b.json",
"PE_MCP_CLIENT_NAME": "Claude Desktop (Client B)"
}
}
}
}Faça login separadamente sob cada nome de servidor, autorizando a conta PushEngage que você escolher no navegador a cada vez. Cada entrada de servidor mantém seu próprio arquivo de token, então alternar entre contas de clientes é uma questão de qual nome de ferramenta você chama, não um novo login a cada vez. Se este é o seu caso de uso real, a série tem um tutorial completo sobre como executar várias contas de clientes PushEngage a partir de um único assistente de IA.
O que fazer depois de conectado
Com a autenticação feita e um site selecionado, as 27 ferramentas se dividem em alguns grupos práticos que valem a pena conhecer pelo nome, não apenas pela quantidade.
Para o trabalho diário de execução de campanhas, a série cobre como enviar e agendar notificações push do seu assistente de IA em vez do painel, e como fazer testes A/B de notificações push e deixar a IA escolher o vencedor por taxa de cliques. Para construir sua lista, há um guia completo para construir segmentos de assinantes em linguagem simples.
Para medição, ler análises de notificações push através do seu assistente de IA detalha resumos vitalícios e séries temporais dia a dia. Essas são as mesmas ferramentas de análise que tornam um resultado de teste A/B ou um envio de campanha dignos de relatório, não apenas de execução. A série também cobre a auditoria de campanhas de gotejamento e fluxos de trabalho para verificar o que está realmente ativo, e o gerenciamento do widget de chat que exibe WhatsApp e outros canais no local.
Para trabalho em nível de site, alterar configurações de sites PushEngage a partir de um assistente de IA cobre fuso horário, geolocalização e configuração do service worker. E se você estiver configurando isso para mais de uma conta PushEngage, a postagem focada em agências sobre como executar várias contas de clientes PushEngage a partir de um único assistente de IA (link acima) aprofunda mais do que o exemplo de configuração neste guia.
Se você estiver configurando isso para alguém com menos conhecimento técnico (um fundador que deseja que o assistente de IA cuide do PushEngage no dia a dia sem tocar em um arquivo de configuração), a primeira semana de um fundador não técnico com o PushEngage MCP é a versão narrativa desta mesma configuração, escrita para esse leitor.
A configuração em si funciona da mesma forma, independentemente do seu plano PushEngage. Todos os planos PushEngage, incluindo o nível gratuito, suportam o servidor MCP. Se você estiver decidindo qual plano se encaixa antes de conectar qualquer coisa, a página de preços do PushEngage tem os níveis atuais.
