Agentes de IA (MCP)

O zero-mcp expõe as operações da API do Zero como ferramentas para qualquer agente que fale MCP (Model Context Protocol).

Ele nasce do contrato da API: não existe ferramenta que não seja uma operação pública. Quando a API ganha uma operação, o agente ganha a ferramenta — sem uma linha de código nova.

Instalar

Baixe o binário do seu sistema em zero.nnumbers.com.br/downloads e confira o checksum, como na CLI.

Configurar

A credencial é a mesma da CLI, e vai por variável de ambiente — nunca por argumento:

{
  "mcpServers": {
    "zero": {
      "command": "/usr/local/bin/zero-mcp",
      "args": ["--org", "org_01..."],
      "env": {
        "ZERO_API_BASE_URL": "https://api.zero.nnumbers.com.br",
        "ZERO_TOKEN": "..."
      }
    }
  }
}

A organização é obrigatória. Sem escopo de tenant, toda ferramenta dependeria de o servidor adivinhar em qual organização agir — e adivinhar errado seria agir no lugar errado.

Os três modos de permissão

Esta é a decisão que importa. Um servidor MCP roda ao lado de um agente com a credencial de alguém, e o modo seguro é o que não muda nada.

Flags	Ferramentas	O que libera
(nenhuma)	77	Só leitura. O padrão.
--permitir-mutacao	121	Criar, alterar, publicar, escalar
--permitir-mutacao --permitir-destrutiva	128	Apagar, cancelar, reverter

O padrão é o modo que não escreve. Ligar mutação é uma decisão consciente de quem configura o agente, não um efeito colateral de instalar.

Antes de ligar o modo destrutivo

Ele inclui apagar projeto e ambiente. Um agente com essa permissão e um mal-entendido de contexto apaga o que ninguém pediu para apagar. Comece pelo padrão, e suba um degrau de cada vez.

O que o agente enxerga

As mesmas fronteiras de qualquer cliente da API: os papéis da sua conta valem igual, recurso de outra organização responde "não existe", e toda operação fica na trilha de auditoria com o autor. O agente não é um caminho privado — é mais um cliente do mesmo contrato.

A rede entre projetos: o agente lê, e não abre caminho

As leituras da rede entre projetos estão em todos os modos: as redes e quem está nelas (zero_networks_list, zero_networks_get), as permissões (zero_networks_grants_list, zero_networks_grants_get), a rede de um ambiente (zero_environments_network_get), a visão de um projeto — quem chega, para onde sai, os endereços internos (zero_projects_network_access) — e as entradas internas do Gateway (zero_gateways_private_entries_*).

Nenhum modo abre tráfego entre projetos. Criar ou excluir rede, pôr ambiente numa rede, conceder ou revogar permissão, mudar a exposição do projeto, dar nome interno a um serviço e mexer nas entradas internas não viram ferramenta, nem com --permitir-mutacao --permitir-destrutiva: abrir um caminho entre projetos é decisão de uma pessoa. Com as leituras, o agente responde "quem alcança o quê" e diz exatamente o que pedir.

Isso vale para o acesso de pessoas: com permissão de escrita, "conceda acesso à Carolina" vira procurar a pessoa no provedor de identidade (zero_users_list) e conceder ao identificador encontrado (zero_access_grant). Revogar acesso é destrutivo e só existe no modo que libera destruição. Nenhuma ferramenta recebe ou devolve senha. Ver Usuários e acesso.