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.
Nenhum disso exige que o assistente tenha a sua palavra-passe do PushEngage, e nenhum disso exige que saia do seu editor ou terminal. O PushEngage executa esta integração para uma base de contas de mais de 75.000 empresas 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 o volume é executado, não com 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 fala 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, usando 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
Claude Code utiliza MCP através de stdio da mesma forma que Claude Desktop e 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, 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 |
|---|---|---|
Claude Desktop | 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". |
~/.pushengage/mcp.json | ~/.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 |
|---|---|
autenticação_login_pushengage | Abre o navegador para o PushEngage e armazena o token em caso de sucesso. |
estado_autenticação_pushengage | Mostra se está autenticado e qual o site atualmente selecionado. |
listar_sítios_pushengage | Lista os sites PushEngage aos quais a sua conta pode aceder. |
selecionar_sítio_pushengage | 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 erro 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 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.
