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:
- 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.
- O cliente abre o PrimeForge no navegador. Se você não estiver logado, entre normalmente (com o 2FA, se ativo).
- 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
.envdos 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çalhosAuthorization, chavesAPP_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>etail -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
- Logs e Auditoria — o que cada papel enxerga nos logs do painel.
- Equipe e Conta — papéis (RBAC) e 2FA.
- Solução de Problemas — problemas comuns e como resolver.