Conecte um cliente MCP ao seu Node

O seu Node já sabe tudo o que você abriria o Console para descobrir: quais eventos chegaram, quais vendas foram registradas, o que falhou em silêncio, quanto cada anúncio gastou. O endpoint MCP entrega isso a um agente de IA seu — Claude Desktop, um agente de IDE, uma ferramenta que você mesmo escreveu — para que você pergunte em português em vez de navegar por telas.

O agente lê do seu Node, com uma chave sua, direto do seu servidor. Nada é intermediado pelo Supreme.

Tempo estimado: 10 minutos.

O que é o endpoint MCP do Node

MCP (Model Context Protocol) é o protocolo que um cliente de IA usa para descobrir e chamar ferramentas. O Node expõe o dele em um endereço só:

POST https://SEU-NODE/mcp/dispatch.php

Características que importam na hora de configurar um cliente:

Se o seu Node estiver instalado de forma que a raiz do domínio já aponte para a pasta pública, https://SEU-NODE/public/mcp/dispatch.php também responde. As duas formas chegam ao mesmo lugar; use a que responder 200 no teste da Etapa 2.

A chave: MCP_KEY

Por que ela não é a MASTER_KEY

A MASTER_KEY é a chave de administração do Node. Quem a tem entra no Console, muda configuração, cria e apaga Propriedades, edita credenciais de integração. Entregar a MASTER_KEY para um agente de IA seria entregar o Node inteiro.

A MCP_KEY existe justamente para isso não ser necessário. Ela abre somente o endpoint MCP, e o endpoint MCP só faz leitura. São chaves diferentes, guardadas separadamente, e uma não substitui a outra:

• colar a MASTER_KEY no cabeçalho X-MCP-Key devolve 401;
• a MCP_KEY não serve para entrar no Console.

O endpoint aceita um segundo cabeçalho, X-Agent-Key, que é a via usada pelo próprio System nos recursos assistidos. Para conectar o seu agente, use X-MCP-Key.

Onde ela mora

A MCP_KEY fica no arquivo .env do Node, no seu servidor, e também nas configurações internas do Node — a segunda cópia é o que garante que uma atualização não deixe o endpoint sem chave.

A partir da versão 4.0.0 ela é gerada durante a instalação. Um Node instalado antes disso ganha a dele na primeira atualização para 4.0.0.

Uma atualização nunca troca a MCP_KEY. Quando já existe uma, o Node a mantém como está. Se o seu agente parou de funcionar depois de um update, a causa está em outro lugar.

A MCP_KEY não aparece em nenhuma tela do Console. Ela é lida do arquivo .env do Node, e é assim de propósito: uma chave que nenhuma interface exibe é uma chave que não vaza em captura de tela.

Etapa 1 — Pegue a MCP_KEY

Acesse o seu servidor por SSH ou pelo gerenciador de arquivos da hospedagem e abra o .env na raiz da instalação do Node. Procure a linha:

MCP_KEY=...

O valor é uma sequência longa de caracteres hexadecimais. Copie inteiro, sem espaços.

Se a linha não existir, o Node é anterior à 4.0.0 e ainda não foi atualizado. Atualize para 4.0.0 ou mais recente e ela aparece.

Trate a MCP_KEY como senha: não coloque em repositório público, em prompt compartilhado, nem em ticket de suporte.

Etapa 2 — Teste o endpoint antes de configurar o cliente

Isso separa "o Node não responde" de "o meu cliente está mal configurado". De qualquer terminal:

curl -s -X POST "https://SEU-NODE/mcp/dispatch.php" \
  -H "X-MCP-Key: SUA_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

O que a resposta diz:

Um teste mais curto, só para provar a autenticação:

curl -s -X POST "https://SEU-NODE/mcp/dispatch.php" \
  -H "X-MCP-Key: SUA_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

Etapa 3 — Configure o cliente

Cada cliente MCP declara servidores remotos do seu próprio jeito, e os nomes dos campos variam. O que não varia é o que você precisa informar: a URL, o cabeçalho e o valor da chave.

A forma mais comum é um bloco parecido com este:

{
  "mcpServers": {
    "supreme-node": {
      "url": "https://SEU-NODE/mcp/dispatch.php",
      "headers": {
        "X-MCP-Key": "SUA_MCP_KEY"
      }
    }
  }
}

Troque SEU-NODE pelo domínio do seu Node e SUA_MCP_KEY pelo valor da Etapa 1. Consulte a documentação do seu cliente para saber onde esse arquivo fica e como ele nomeia a URL e os cabeçalhos.

Depois de reiniciar o cliente, peça a ele que liste as ferramentas disponíveis. Devem aparecer 11.

O que o agente pode perguntar

São 11 ferramentas, em cinco famílias.

Diagnóstico e logs — 4 ferramentas

node_list_diagnostics · node_get_diagnostic · node_ack_diagnostics · node_search_logs

O Node detecta falhas silenciosas enquanto processa: venda sem identificador, evento recusado na validação, encaminhamento que falhou, webhook rejeitado. Cada achado carrega código, nível, status, mensagem e contexto operacional. Os logs de sistema podem ser buscados por nível, canal, texto ou id de evento.

"Tem alguma coisa falhando em silêncio no meu Node nos últimos dias? Me mostra o log do achado mais grave."

Eventos e payloads — 2 ferramentas

node_get_events · node_get_event_payload

A lista de eventos recentes, com filtros, e o payload armazenado de um evento ou de uma compra por vez.

"Chegou algum purchase na última hora? Abre o payload da última e me diz se ela veio com utm_content."

Compras — 1 ferramenta

node_get_purchase_summary

Receita total, contagem e quebra por plataforma em um período. Agregado, nunca linha a linha.

"Quanto o Node registrou de receita nos últimos 30 dias, por plataforma?"

Integrações — 1 ferramenta

node_list_integrations

Quais módulos estão instalados neste Node e se estão ativos.

"Quais integrações estão instaladas e ativas aqui?"

Anúncios — 3 ferramentas

ads_list_connections · ads_get_summary · ads_get_insights

As mesmas leituras da seção Insights do Console: as contas conectadas e o estado da sincronização; o resumo de investimento, CPA e ROAS de um período com a série diária; e o desempenho agregado por anúncio, conjunto ou campanha — opcionalmente cruzado com a receita que o Node mediu.

"Como foram os anúncios nos últimos 7 dias? Lista os 10 anúncios que mais gastaram com o ROAS atribuído de cada um."

O cruzamento por anúncio depende do macro utm_content nos criativos, exatamente como no Console — veja Conecte o Meta Ads ao seu Node.

O que o agente não pode fazer

O endpoint é de leitura. Ele não cria, não configura e não encaminha nada.

• Nenhuma mudança de configuração. Não há ferramenta que crie Propriedade, instale módulo, edite credencial, dispare encaminhamento ou altere ajuste do Node.
• Nenhuma credencial sai. A lista de integrações omite a configuração dos módulos. A lista de conexões de anúncios nunca devolve o token de acesso.
• Payloads passam por um redator. Ao abrir o payload de um evento ou de uma compra, os dados pessoais são mascarados dentro do Node, antes de a resposta sair. O agente pode citar uma máscara; ele nunca recebe o valor real.
• Uma ferramenta por registro. O payload é lido de um evento ou de uma compra por chamada — não há intervalo de datas nem exportação em massa por esse caminho.

Uma exceção, e vale conhecê-la: node_ack_diagnostics escreve. Ela marca achados de diagnóstico como lidos ou resolvidos — o mesmo que você faria clicando no Console. É a única ferramenta que altera estado, ela não toca em configuração nem em dado de evento, e "lido" é um fato seu: peça ao seu agente que só marque com a sua confirmação explícita.

Resolvendo um 401

Um 401 com AUTH_INVALID_MCP_KEY quer dizer uma coisa só: a chave enviada não bate com a que o Node tem. Não é firewall, não é CORS, não é o modelo.

Confira nesta ordem:

1. O cabeçalho é X-MCP-Key? Não é Authorization, não é X-Master-Key.
2. O valor está inteiro? Copiar do terminal costuma cortar o fim ou colar uma quebra de linha no meio. Compare o começo e o fim com o .env.
3. É a MCP_KEY mesmo? A MASTER_KEY e a INGEST_TOKEN moram no mesmo arquivo e são igualmente longas. O endpoint MCP não aceita nenhuma das duas.
4. A linha MCP_KEY= existe no .env? Se não, o Node é anterior à 4.0.0 ou não foi atualizado. Sem chave configurada, o endpoint recusa todo mundo, sempre — inclusive uma tentativa com a chave certa de outro Node.
5. É o Node certo? Cada Node tem a sua própria MCP_KEY. A chave de um ambiente de teste não abre o de produção.

Uma atualização não é causa provável: o Node preserva a MCP_KEY existente ao atualizar.

Se o teste com curl da Etapa 2 responde e o cliente não, o problema está na configuração do cliente — quase sempre o cabeçalho, que alguns clientes exigem em um campo com outro nome.

Boas práticas

• Uma chave por Node. Não reaproveite a mesma MCP_KEY em vários Nodes; cada um gera a sua.
• Prefira HTTPS sempre. A chave viaja em um cabeçalho; sem TLS ela viaja em texto claro.
• Revise antes de aprovar escrita. Configure o seu cliente para pedir confirmação antes de chamar node_ack_diagnostics.
• Trate a resposta como dado do seu negócio. O agente lê do seu servidor, mas o que você faz com a resposta depois — colar em um chat, em um documento compartilhado — é seu.

Para conectar a conta de anúncios que alimenta as três ferramentas de anúncios, veja Conecte o Meta Ads ao seu Node.