Zenifra MCP

O Zenifra MCP conecta clientes de IA compatíveis à sua conta Zenifra para consultas autorizadas sobre projetos, métricas, builds, consumo e pagamentos. A conexão usa OAuth no navegador e permanece somente leitura.

O que é o Zenifra MCP

O Model Context Protocol (MCP) permite que um cliente de IA consulte informações de um serviço conectado. No Zenifra, o endpoint público é:

https://mcp.zenifra.com/mcp

O Zenifra MCP não cria, altera ou remove projetos. Ele apresenta ao cliente somente os dados que a conta conectada está autorizada a consultar. A autorização escolhe uma organização por conexão e permite revisar os acessos antes da confirmação.

O que você pode acessar

Depois do OAuth, o cliente pode consultar, conforme os acessos aprovados:

contexto da conta e da organização conectada;
lista de projetos autorizados;
detalhes de um projeto autorizado;
métricas atuais do projeto, quando disponíveis;
builds, deploys e logs autorizados do projeto;
saúde, instâncias, rede e auto-scaling das aplicações;
status dos projetos Valkey;
informações dos modelos e chaves de IA autorizados, sem credenciais;
consumo de IA em um período móvel;
informações de medição e cobrança dos projetos;
transações da organização quando o acesso financeiro for autorizado separadamente.

O servidor MCP publica nomes de tools concisos:

Tool	Finalidade
`get_context`	Consultar o contexto da conta e organização conectadas.
`list_projects`	Listar projetos autorizados.
`get_project`	Consultar um projeto autorizado.
`get_project_metrics`	Consultar métricas atuais de um projeto.
`list_builds`	Listar informações de builds do projeto.
`get_project_logs`	Consultar logs recentes e limitados de uma aplicação.
`get_build_logs`	Consultar logs paginados de um build.
`list_deployments`	Listar deploys registrados no mês atual.
`get_project_health`	Consultar a configuração e disponibilidade do health check.
`list_healthcheck_failures`	Listar falhas recentes de health check.
`get_project_network`	Consultar resumos, rotas, respostas e eventos de rede.
`get_project_autoscaling`	Consultar a configuração atual de auto-scaling.
`list_autoscaling_events`	Listar eventos recentes de aumento ou redução de capacidade.
`list_project_instances`	Listar os identificadores públicos das instâncias.
`get_valkey_status`	Consultar o status e a configuração pública de um projeto Valkey.
`list_ai_keys`	Listar informações de chaves de IA autorizadas, sem credenciais.
`get_ai_usage`	Consultar o consumo observado de IA.
`get_project_billing`	Consultar medições ou lançamentos de um projeto.
`list_transactions`	Listar transações autorizadas da organização.

Os clientes podem exibir o namespace do servidor antes desses nomes. Com um servidor chamado zenifra, por exemplo, get_context pode aparecer como zenifra_get_context. Não adicione zenifra_ ao nome da própria tool MCP.

Os dados financeiros exigem consentimento próprio durante a autorização. A ausência de acesso financeiro não impede as consultas de projetos e métricas permitidas.

Antes de conectar

Tenha uma conta Zenifra ativa, acesso à organização que deseja consultar e um cliente que suporte servidores MCP remotos por HTTPS com OAuth. Use sempre o endpoint completo terminado em /mcp.

Você não precisa criar um token manual nem informar uma credencial estática ao cliente. O login acontece no navegador quando o cliente inicia o fluxo OAuth.

Onde adicionar a configuração

Prefira o comando do próprio cliente quando ele estiver disponível. O comando grava a configuração no formato esperado e reduz o risco de editar o arquivo errado. Para configuração manual, estes são os caminhos mais comuns em Linux e macOS:

Cliente	Configuração do usuário	Configuração do projeto
Codex	`~/.codex/config.toml`	`<projeto>/.codex/config.toml`
Claude Code	`~/.claude.json`	`<projeto>/.mcp.json`
OpenCode	`~/.config/opencode/opencode.json` ou `.jsonc`	`<projeto>/opencode.json` ou `<projeto>/.opencode/opencode.json`
Pi	`~/.pi/agent/mcp.json` ou `~/.config/mcp/mcp.json`	`<projeto>/.mcp.json` ou `<projeto>/.pi/mcp.json`
Hermes Agent	`~/.hermes/config.yaml`	—

~ representa a pasta pessoal do usuário. Uma configuração de usuário fica disponível em vários projetos; uma configuração de projeto acompanha somente aquele diretório e pode ser compartilhada com a equipe quando o cliente permitir.

No Codex e no Claude Code, prefira codex mcp add e claude mcp add para gravar a configuração. No OpenCode e no Pi, edite o JSON/JSONC ou use o gerenciamento do próprio cliente. No Hermes Agent, edite o YAML e execute hermes mcp login zenifra.

Adicione somente a URL pública e os campos indicados neste guia. Não coloque access tokens, refresh tokens, client secrets ou cookies nesses arquivos. Cada cliente armazena as credenciais OAuth pelo próprio fluxo de autenticação. No Windows, prefira os comandos do cliente e consulte sua referência oficial para localizar o arquivo correspondente.

Conectar pelo Codex

Adicione o servidor e inicie o login pelo terminal:

codex mcp add zenifra --url https://mcp.zenifra.com/mcp
codex mcp login zenifra
codex mcp list

O navegador será aberto para o login e para a revisão do consentimento. Depois de autorizar, use codex mcp list para confirmar que o servidor está conectado. O aplicativo Codex também permite cadastrar o servidor e iniciar o OAuth pelas configurações de MCP.

Consulte a referência oficial de MCP do Codex para opções específicas da versão instalada.

Conectar pelo Claude Code

Adicione o servidor no escopo do usuário:

claude mcp add --transport http --scope user zenifra https://mcp.zenifra.com/mcp
claude mcp list

O Claude Code inicia o OAuth quando você usa o servidor pela primeira vez ou solicita a autenticação do servidor. Faça login no navegador, revise a organização e os acessos e confirme. Depois, use claude mcp list para verificar o status.

Consulte a referência oficial de MCP do Claude Code para os comandos de gerenciamento disponíveis na sua versão.

Conectar pelo OpenCode

O Zenifra oferece registro automático de cliente público nos dois formatos. Não adicione clientId, clientSecret, client_id ou client_secret à configuração.

OpenCode 1.x

Para o OpenCode 1.x, incluindo a série 1.18, adicione o servidor remoto diretamente dentro de mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "zenifra": {
      "type": "remote",
      "url": "https://mcp.zenifra.com/mcp",
      "enabled": true
    }
  }
}

Inicie a autenticação e confirme o status pelo terminal:

opencode mcp auth zenifra
opencode mcp list

O fluxo no navegador seleciona a organização Zenifra, os recursos e os acessos da conexão. O servidor OpenCode 1.x só está pronto quando opencode mcp list informar que ele está conectado.

OpenCode V2

Para o OpenCode V2, use mcp.servers.zenifra:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "zenifra": {
        "type": "remote",
        "url": "https://mcp.zenifra.com/mcp"
      }
    }
  }
}

A referência oficial do OpenCode V2 apresenta a interface de gerenciamento MCP para autenticar servidores remotos. Abra essa interface, inicie a autenticação do servidor Zenifra e conclua o OAuth no navegador. O fluxo seleciona a organização Zenifra, os recursos e os acessos da conexão. O servidor OpenCode V2 só está pronto quando a interface MCP V2 informar que ele está conectado.

Consulte a referência oficial de servidores MCP do OpenCode e a referência oficial do OpenCode V2 para detalhes do formato e da autenticação.

Conectar pelo Pi

Instale o pacote que adiciona suporte a servidores MCP no Pi:

pi install npm:pi-codemcp

Adicione o servidor Zenifra à configuração de MCP do Pi:

{
  "mcpServers": {
    "zenifra": {
      "type": "http",
      "url": "https://mcp.zenifra.com/mcp",
      "auth": "oauth"
    }
  }
}

No Pi, use /codemcp para iniciar o OAuth e consultar o status da conexão. Autorize a organização desejada no navegador antes de fazer a primeira consulta.

Consulte a referência oficial do pi-codemcp para o caminho da configuração e os comandos disponíveis.

Conectar pelo Hermes Agent

Adicione o servidor HTTP OAuth ao arquivo de configuração do Hermes Agent:

mcp_servers:
  zenifra:
    url: "https://mcp.zenifra.com/mcp"
    auth: oauth

Inicie a autenticação e recarregue as ferramentas MCP quando necessário:

hermes mcp login zenifra

Conclua o OAuth no navegador e confirme que as ferramentas do Zenifra aparecem depois do recarregamento. Para conexões remotas ou sem interface gráfica, siga o guia oficial de OAuth remoto do Hermes Agent.

Verificar a conexão

O fluxo de verificação é o mesmo em todos os clientes:

Cadastre o endpoint HTTPS terminado em /mcp.
Inicie o login OAuth pela ação documentada pelo cliente.
Faça login na Zenifra no navegador.
Selecione uma organização e revise os acessos solicitados.
Autorize a conexão.
Volte ao cliente e confirme que as ferramentas Zenifra estão disponíveis.
Faça uma primeira consulta pelo contexto conectado ou pela lista de projetos autorizados.

Antes de concluir o OAuth, uma requisição sem autenticação retorna 401. Esse é o desafio esperado para iniciar a autorização. Considere a conexão verificada somente quando o OAuth terminar e uma consulta somente leitura retornar dados que sua conta pode visualizar.

Permissões e reconexão

Cada conexão OAuth fica associada à organização escolhida durante o consentimento. Para consultar outra organização, reconecte a conta e selecione a nova organização quando o cliente iniciar o fluxo novamente.

A tela de consentimento também mostra os recursos e acessos solicitados. O acesso financeiro é separado e precisa ser aprovado explicitamente. Se você alterar a organização ou os acessos desejados, use a ação de reconexão do cliente e revise o consentimento outra vez.

Solucionar problemas

Nenhum prompt de OAuth: confirme que a URL termina em /mcp e inicie a ação de login do cliente.
401 depois do login: reconecte a conta Zenifra e conclua o consentimento novamente.
403 ou dados ausentes: reconecte e revise a organização, os recursos e os acessos selecionados.
Nenhuma ferramenta disponível: confirme que o servidor está habilitado, autenticado e recarregado no cliente.
Falha em conexão remota ou sem interface gráfica: siga o guia oficial de autenticação remota do cliente escolhido.

Exemplos de prompts

Depois de verificar a conexão, experimente consultas como:

Qual organização está conectada?

Liste os projetos que posso consultar.

Mostre as métricas atuais do projeto autorizado que eu indicar.

Liste os builds recentes do projeto selecionado e mostre os logs do build que eu indicar.

Verifique a saúde, as instâncias e os eventos de auto-scaling deste projeto.

Mostre um resumo da rede da última hora e as falhas recentes de health check.

Mostre meu consumo de IA no período disponível e as transações autorizadas.

O cliente só deve responder com dados cobertos pelo consentimento da conexão.

Próximos passos e referências oficiais

Usar a CLI da Zenifra para operações no terminal, incluindo ações compatíveis de criação e alteração.
Autenticação na Zenifra para entender as formas de login da plataforma.
MCP do Codex
MCP do Claude Code
Servidores MCP do OpenCode estável/1.x
Servidores MCP do OpenCode V2
pi-codemcp
MCP do Hermes Agent

Nessa página