Já tem o Claude Desktop, Claude Code ou Cursor abertos mais horas por dia do que o painel PushEngage. Todas as vezes que precisar de verificar uma taxa de cliques ou enviar uma notificação, sai da janela onde o trabalho real está a acontecer. A configuração do MCP PushEngage fecha essa lacuna: um comando npx, um início de sessão no navegador, e as ferramentas do PushEngage ficam dentro da mesma sessão de chat que já está a usar para escrever código, depurar um fluxo de trabalho ou responder a uma pergunta da sua equipa.
Este é o guia de configuração completo: instalação, as duas variáveis de ambiente que vale a pena conhecer, o primeiro login, e as três coisas específicas que quebram a ligação quando ela não funciona logo à primeira tentativa. No final, terá uma sessão autenticada com um site selecionado, não apenas um indicador verde de “ligado”.
O que poderá fazer depois de estar ligado
@pushengage/mcp envia 27 ferramentas em 10 domínios, e depois de se autenticar num site, todas elas estão a uma frase de distância em vez de a um clique do painel. Alguns exemplos do que isso parece depois de a configuração estar concluída:
- Envie uma notificação push agora, agende-a para uma hora específica, ou configure um envio recorrente — no fuso horário local de cada assinante, se o solicitar.
- Execute um teste A/B entre duas manchetes e deixe o assistente reportar 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.
- Extraia análises como um resumo vitalício ou como uma série temporal dia a dia.
- Liste as suas campanhas de gotejamento, campanhas acionadas e fluxos de trabalho para verificar o que está realmente a ser executado.
- Leia as configurações do seu site, a configuração do service worker e a configuração do widget de chat.
Nada disso requer que o assistente tenha a sua palavra-passe PushEngage, e nada disso requer que 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 mil milhõ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 uma demonstração em sandbox.
Antes de começar: o que precisa
Três coisas, e 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 si; opera em sites que já configurou no seu painel PushEngage.
- Node.js 18 ou mais recente — o assistente executa o servidor através de
npx, que vem com o Node. Verifique comnode -vnum terminal. - Um cliente compatível com MCP — Claude Desktop, Claude Code, Cursor ou qualquer outro cliente que utilize MCP através de entrada/saída padrão (stdio).
Uma coisa que vale a pena afirmar claramente antes de começar a editar ficheiros de configuração: @pushengage/mcp é executado localmente na sua máquina através de stdio. Não existe um servidor remoto para apontar e nenhum URL de conector alojado. O cliente inicia o processo, e o processo comunica com a API do PushEngage em seu nome. Se um guia de configuração para outra ferramenta lhe disser para colar um ponto final remoto, esse é um tipo diferente de servidor MCP do que este.
Configurar o servidor no Claude Desktop, Claude Code e Cursor
Sem instalação global. npx obtém @pushengage/mcp sob demanda na primeira vez que o seu cliente o inicia, utilizando o comando exato npx -y @pushengage/mcp. 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 a sua configuração num 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” deverá aparecer na sua lista de ferramentas.
Cursor
Edite ~/.cursor/mcp.json:
{
"mcpServers": {
"pushengage": {
"command": "npx",
"args": ["-y", "@pushengage/mcp"]
}
}
}Claude Code
O Claude Code comunica com MCP através de stdio da mesma forma que o Claude Desktop e o Cursor, pelo que a mesma estrutura command/args funciona se editar diretamente o seu ficheiro de configuração MCP. Se preferir não editar manualmente o JSON, o Claude Code também aceita servidores através do 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 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 todo o lado: configure-o para executar npx -y @pushengage/mcp como um servidor stdio. Esse é todo o passo de instalação, independentemente de qual cliente lê a configuração.
Nomear a ligação e isolar tokens: PE_MCP_CLIENT_NAME e PE_MCP_CONFIG_PATH
Não é necessária nenhuma configuração além do passo de instalação. O servidor comunica com a API de produção do PushEngage por defeito; existem duas variáveis de ambiente para configurações menos comuns:
| Variável de ambiente | Padrão | Propósito |
|---|---|---|
PE_MCP_CLIENT_NAME | Assistente de IA | O rótulo mostrado no ecrã de autorização do PushEngage como a aplicação que solicita 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 isto 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 de tocar em nenhuma das variáveis. PE_MCP_CLIENT_NAME é uma conveniência cosmética, útil se quiser que o ecrã de autorização diga algo mais legível do que “Assistente de IA” quando for você a clicar em Autorizar. PE_MCP_CONFIG_PATH é importante no momento em que precisar de um segundo ficheiro de token separado, que é exatamente o caso abordado a seguir.
Primeira execução: iniciar sessão e escolher um site
A autenticação é baseada no navegador, pelo que o assistente nunca vê a sua palavra-passe PushEngage. O fluxo tem três passos e vale a pena analisar o que cada um chama internamente:
- Peça ao assistente para iniciar sessão. Em linguagem simples: “Faz-me iniciar sessão no PushEngage.” Isto invoca
pushengage_auth_login, que abre um separador no navegador para a página de autorização do PushEngage. - Clique em Autorizar. O painel envia o token para o servidor como um pedido POST — nunca aparece num URL, histórico do navegador ou registo de acesso. O token é guardado localmente com permissões
0600, legível apenas pelo seu utilizador. - Peça ao assistente para mostrar os seus sites e, em seguida, escolha um. “Mostra os meus sites PushEngage” chama
pushengage_list_sites; “Usa o site 12345” chamapushengage_select_site. A seleção é lembrada entre reinícios, e todas as ferramentas com âmbito de site agem sobre ela, a menos que 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 está autenticado e qual o site atualmente selecionado. |
pushengage_list_sites | Lista os sites PushEngage a que a sua conta pode aceder. |
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 meu estado de autenticação PushEngage” é suficiente) e confirme que 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 pela primeira vez o servidor como conectado.
Resoluçã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 todo e o seu cliente mostra “Conexão fechada.” Isto é quase sempre um problema de PATH, não um bug no servidor. Claude Desktop, Cursor e clientes semelhantes são lançados a partir do seu Dock ou Finder, não de um terminal, pelo que nunca carregam os ficheiros de inicialização do seu shell. Se o Node foi instalado através de um gestor de versões (nvm, fnm, volta), o cliente não consegue encontrar npx de todo. O processo nunca começa e recebe um erro de conexão genérico em vez de um claro “comando não encontrado.” Execute which npx num terminal para obter o caminho absoluto e, em seguida, aponte o 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 em vez disso imprimir um caminho em /usr/local/bin ou /opt/homebrew/bin, um gestor de versões provavelmente não é o seu problema; verifique os próprios registos MCP do cliente para o erro real.
[AUTH_EXPIRED]. O seu token expirou. Peça ao assistente para iniciar sessão novamente — essa é toda a correção.
[NO_SITE_SELECTED]. Está autenticado, mas nenhum site foi escolhido ainda. Chame pushengage_list_sites, depois peça para usar um dos sites retornados, antes de tentar novamente qualquer ferramenta com âmbito de site.
Mais um caso que vale a pena saber, embora não seja um erro: se o navegador não abrir automaticamente, é provável que esteja numa sessão headless ou remota (SSH, um contentor). O URL de autorização é impresso no terminal que executa o servidor. Abra-o manualmente.
Executar mais do que uma conta ou cliente PushEngage
Se gere o PushEngage para mais do que uma marca, ou se é uma agência a executar o MCP contra várias contas de clientes, a solução é o PE_MCP_CONFIG_PATH de antes: registe o servidor sob dois nomes diferentes, cada um com o 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)"
}
}
}
}Inicie sessão em cada nome de servidor separadamente, autorizando a conta PushEngage que escolher no navegador de cada vez. Cada entrada de servidor mantém o seu próprio ficheiro de token, pelo que alternar entre contas de clientes é uma questão de qual nome de ferramenta chama, não um novo início de sessão a cada vez. Se este é o seu caso de uso real, a série tem um tutorial completo sobre executar múltiplas contas de clientes PushEngage a partir de um assistente de IA.
O que fazer depois de estar conectado
Com a autenticação feita e um site selecionado, as 27 ferramentas dividem-se em alguns grupos práticos que vale a pena conhecer pelo nome, não apenas pela contagem.
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 de controlo, e como fazer testes A/B de notificações push e deixar a IA escolher o vencedor por taxa de cliques. Para construir a sua lista, existe um guia completo para construir segmentos de subscritores em linguagem clara.
Para medição, ler análises de notificações push através do seu assistente de IA aborda 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 digno 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 a gestão do widget de chat que exibe WhatsApp e outros canais no local.
Para trabalho a nível de site, alterar as definições do site PushEngage a partir de um assistente de IA cobre o fuso horário, geolocalização e configuração do service worker. E se estiver a configurar isto para mais do que uma conta PushEngage, a publicação focada em agências sobre a execução de múltiplas contas de clientes PushEngage a partir de um assistente de IA (ligada acima) aprofunda mais do que o exemplo de configuração neste guia.
Se estiver a configurar isto para alguém menos técnico (um fundador que quer que o assistente de IA lide com o PushEngage no dia a dia sem tocar num ficheiro de configuração), a primeira semana de um fundador não técnico com PushEngage MCP é a versão narrativa desta mesma configuração, escrita para esse leitor.
A configuração funciona da mesma forma, independentemente do seu plano PushEngage. Todos os planos PushEngage, incluindo o nível gratuito, suportam o servidor MCP. Se estiver a decidir qual plano se adequa antes de ligar qualquer coisa, a página de preços da PushEngage tem os níveis atuais.
