Servidor MCP (Assistentes de IA)

O PrimeForge tem um servidor MCP (Model Context Protocol) para você conectar um assistente de IA — Claude, ChatGPT, Cursor, VS Code e outros clientes compatíveis — à sua frota. Com ele, você pergunta em linguagem natural sobre a saúde de um, de vários ou de todos os seus sites e servidores, e o assistente lê os mesmos dados do painel (status, métricas, incidentes, deploys, atividade e logs) para explicar o que está acontecendo e como resolver.

O servidor é somente leitura. Pelo MCP, nada é alterado, executado, reiniciado ou publicado — o assistente não roda comandos, scripts nem deploys. Quando ele encontra a solução, ele explica o que fazer e manda o link direto para a página do painel (ou da documentação) onde você faz.

Como conectar

O endereço do servidor é:

https://primeforge.dev.br/mcp

A autenticação é OAuth 2.1, o padrão do protocolo MCP — você não copia token nenhum:

  1. No seu cliente de IA, adicione um servidor MCP remoto (HTTP) com o endereço acima. Exemplos:
    • Claude (claude.ai / Claude Desktop): Configurações › Conectores › Adicionar conector personalizado e cole a URL.
    • Claude Code: claude mcp add --transport http primeforge https://primeforge.dev.br/mcp
    • Cursor / VS Code: adicione um servidor com "url": "https://primeforge.dev.br/mcp" na configuração de MCP.
  2. O cliente abre o PrimeForge no navegador. Se você não estiver logado, entre normalmente (com o 2FA, se ativo).
  3. Na tela Conectar um assistente de IA ao PrimeForge, confira o nome do aplicativo, a conta e — principalmente — o endereço para onde o acesso será entregue (em negrito); só autorize se for o do seu assistente. Então clique em Autorizar.

O acesso vale por 8 horas e é renovado automaticamente pelo cliente por até 30 dias; depois disso, o cliente pede uma nova autorização.

O que o assistente enxerga

O assistente enxerga exatamente o que você enxerga no painel, com o seu papel em cada organização:

  • Só as organizações de que você é membro com convite aceito.
  • O servidor do painel PrimeForge não aparece (só para superadministradores); um site seu hospedado nele aparece, com o servidor indicado como "Painel PrimeForge".
  • As leituras sensíveis seguem as mesmas regras do painel:
O quê Papel mínimo
Servidores, sites, saúde, métricas, incidentes, deploys (log) qualquer membro
Logs do site (aplicação, nginx, workers) qualquer membro
Saída completa de um deploy que falhou, de comandos e tarefas agendadas Developer
Log de atividade (auditoria) Developer (o que cada papel vê é o mesmo do Log de Auditoria)
Logs do servidor (nginx, PHP-FPM, bancos, Redis, agente…) Developer
Logs de segurança do servidor (SSH, auth.log, nginx error.log, atualizações) Admin
Saída de scripts de servidor Admin

O que nunca é exposto

  • Nenhum segredo: senhas de banco, chaves S3, chaves de API, tokens, segredos de webhook, chaves SSH e credenciais de serviços nunca entram em uma resposta.
  • O .env dos sites nunca é lido. Os logs de aplicação vêm só dos arquivos de log conhecidos (laravel.log, app.log, error.log, worker.log) dentro das pastas de log do site.
  • Todo texto passa por um filtro de segredos antes de sair: linhas como DB_PASSWORD=…, URLs com usuário e senha, cabeçalhos Authorization, chaves APP_KEY, tokens do GitHub/Stripe/AWS e URLs de webhook aparecem como [REDACTED].

Ferramentas (tools)

Todas são somente leitura. Onde um servidor ou site é pedido, você pode passar o nome/domínio ou o id.

Ferramenta Parâmetros O que retorna
list-organizations — Suas organizações, seu papel em cada uma e quantos servidores e sites têm.
fleet-health organization, only_problems Todos os servidores e sites com um veredito (healthy, warning, critical) e os problemas concretos: status, heartbeat do agente, CPU/memória/disco, serviços parados ou com falha, sites com falha, HTTP fora do ar, Modo de Pânico. É o ponto de partida.
list-servers organization, status, search Servidores com tipo, status, estado do agente, métricas mais recentes, veredito e link do painel.
get-server server Tudo sobre um servidor: status e desde quando, especificações, métricas e médias/picos da última hora, saúde de cada serviço (nginx, PHP, PostgreSQL, MySQL, Redis, SeaweedFS, Reverb), alertas não resolvidos, rede privada (WireGuard), sites hospedados, atualizações do agente, operações de runtime, fim do log de provisionamento (se ainda não ficou pronto), fontes de log disponíveis e links para cada página do servidor no painel.
list-sites organization, server, status, search Sites com tipo, status, servidor, última sonda HTTP, pânico, veredito e link do painel.
get-site site Tudo sobre um site: veredito e problemas, sondas HTTP, verificações de processo, runtime (PHP/Node, branch, commit), dependências (banco, Redis, S3, Reverb) e se cada uma está no ar no seu servidor, uso de recursos por unidade, últimos deploys, heartbeats, histórico de pânico, fontes de log e links para cada página do site no painel.
get-server-logs server, source, lines (100/200/500/1000), contains As últimas linhas de um log do servidor (journal do nginx, de cada PHP-FPM, dos bancos, Redis, SeaweedFS, Reverb e do agente; nginx access/error; SSH/auth; atualizações automáticas). Sem source, lista as fontes e quais o seu papel pode ler. contains filtra as linhas.
get-site-logs site, source, lines (200/500/1000), contains As últimas linhas de um log do site: app (processo PHP-FPM ou Node, onde caem os logs do Laravel), horizon, reverb, cada worker/daemon (unit:…), nginx-access, nginx-error e os arquivos de log da aplicação (file:storage/logs/laravel.log). Sem source, lista as fontes, inclusive os arquivos de log encontrados.
list-deployments site, limit Os últimos deploys: status, origem, commit, etapa e motivo da falha, duração e link.
get-deployment deployment, contains O log completo de um deploy, etapa por etapa, os tempos de cada etapa e — num deploy com falha, para Developer ou acima — a saída completa do comando que falhou (composer, npm, migrate…).
get-activity server / site / organization, since_hours, limit O log de atividade: quem fez o quê e quando (deploys, reinícios, mudanças de configuração, scripts, alertas). Útil para descobrir o que mudou antes de um problema.
get-incidents organization, only_open, limit O feed de incidentes do painel (alertas de métrica, deploys com falha, servidores offline/inacessíveis, heartbeats perdidos, pânico), os alertas de servidor não resolvidos (certificado expirando, unidade travada…) e os pânicos ativos.
get-metrics server ou site, period (1h/6h/24h/7d) Uso de recursos ao longo do tempo em 12 faixas, com média e pico: CPU, memória e disco do servidor, ou CPU, memória e mortes por falta de memória (OOM) de cada unidade do site.
get-job-history server ou site, kind, limit, failed_only Histórico de trabalho em segundo plano com as saídas: execuções do agendador (cron), scripts e comandos, operações de runtime e serviços, e backups.
search-docs query, limit Busca nesta documentação e devolve as seções com um trecho e o link direto para cada uma. Sem query, lista todas as páginas.
read-doc page, section Uma página desta documentação, ou uma seção dela, em markdown com links absolutos — o passo a passo para orientar uma ação no painel.

Toda resposta é JSON, começa com as_of (o instante da leitura, em UTC) e traz as datas em ISO 8601. Os registros trazem panel_url (e, no detalhe, panel_pages) para levar você direto à página certa.

Prompt de diagnóstico

O servidor também oferece o prompt diagnose-problem (target e symptom, ambos opcionais), que conduz o assistente por uma investigação completa: saúde → o que mudou → incidentes → logs → métricas, terminando com a causa, as linhas de log que a provam e a correção a aplicar no painel.

Exemplos de perguntas

  • "Algum dos meus sites está com problema agora?"
  • "Por que o deploy de loja.exemplo.com.br falhou?"
  • "O site api.exemplo.com.br está devolvendo 502 desde as 14h. Descubra a causa."
  • "Qual servidor está com o disco mais cheio, e o que está crescendo?"
  • "O que mudou no Worker 2 nas últimas 24 horas?"
  • "Como eu adiciono um domínio com SSL a um site?" (o assistente consulta esta documentação e manda os links)

Limites e segurança

  • 120 chamadas por minuto por usuário; a rota pública de registro de clientes OAuth aceita 10 por minuto.
  • As leituras de log no servidor são sempre as mesmas leituras fixas e limitadas das páginas de Logs (journalctl -u <unidade> e tail -n <linhas> de arquivos conhecidos), executadas pelo agente — nenhum comando, caminho ou unidade vindo do assistente chega ao servidor.
  • Os arquivos de log da aplicação (file:…) são lidos pelo agente com as permissões do usuário do site (agente 0.4.20 ou mais novo) — um link simbólico plantado no lugar de um log não alcança nada que o próprio site não pudesse ler. Com um agente mais antigo, esses arquivos não são lidos; atualize o agente na visão geral do servidor.
  • Uma organização sem plano ativo (em modo restrito) não aparece para o assistente — para nenhum membro, nem o proprietário — até a assinatura ser regularizada. No período de acesso completo logo após o vencimento, ela continua aparecendo normalmente.
  • Para cortar o acesso de um assistente, abra Conta › Assistentes de IA (menu do avatar → Conta) e clique em Desconectar: o acesso e a renovação são revogados na hora. Trocar a sua senha ou ter o 2FA redefinido pelo suporte desconecta todos os assistentes.

Veja também