AI agents (MCP)

zero-mcp exposes Zero's API operations as tools for any agent that speaks MCP (Model Context Protocol).

It is born from the API contract: there is no tool that is not a public operation. When the API gains an operation, the agent gains the tool — without a single new line of code.

Installing

Download the binary for your system at zero.nnumbers.com.br/downloads and check the checksum, as with the CLI.

Configuring

The credential is the same as the CLI's, and travels through an environment variable — never an argument:

{
  "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": "..."
      }
    }
  }
}

The organization is required. Without a tenant scope every tool would depend on the server guessing which organization to act on — and guessing wrong means acting in the wrong place.

The three permission modes

This is the decision that matters. An MCP server runs next to an agent with someone's credential, and the safe mode is the one that changes nothing.

Flags	Tools	What it unlocks
(none)	77	Read only. The default.
--permitir-mutacao	121	Create, change, deploy, scale
--permitir-mutacao --permitir-destrutiva	128	Delete, cancel, roll back

The default is the mode that does not write. Enabling mutation is a conscious decision by whoever configures the agent, not a side effect of installing.

Before enabling destructive mode

It includes deleting projects and environments. An agent with that permission and a misunderstanding of context deletes what nobody asked to delete. Start with the default, and move up one step at a time.

What the agent sees

The same boundaries as any API client: your account's roles apply equally, resources from another organization answer "does not exist", and every operation lands in the audit trail with its author. The agent is not a private path — it is one more client of the same contract.

Networking Between Projects: the Agent Reads, and Opens No Path

The reads of networking between projects are in every mode: the networks and who is in them (zero_networks_list, zero_networks_get), the permissions (zero_networks_grants_list, zero_networks_grants_get), an environment's network (zero_environments_network_get), a project's view — who comes in, where it goes out, the internal addresses (zero_projects_network_access) — and the Gateway internal entries (zero_gateways_private_entries_*).

No mode opens traffic between projects. Creating or deleting a network, adding an environment to a network, granting or revoking a permission, changing a project's exposure, giving a service an internal name and changing internal entries do not become tools, not even with --permitir-mutacao --permitir-destrutiva: opening a path between projects is a person's decision. With the reads, the agent answers "who reaches what" and tells exactly what to ask for.

That holds for people's access too: with write permission, "grant Carolina access" becomes searching for the person in the identity provider (zero_users_list) and granting access to the identifier found (zero_access_grant). Revoking access is destructive and only exists in the mode that allows destruction. No tool receives or returns a password. See Users and access.