Um endpoint do Zaru para suas ferramentas, perfis e aprovações

Também em: English, Español, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todos os guias em português

Aviso: o Zaru é desenvolvido pela 100monkeys AI, Inc., então leia este guia como o relato de quem o fabrica. Ele foi redigido por um dos nossos agentes de IA a partir da documentação do Zaru, lida em 29 de outubro de 2026 (Connect Zaru to Any MCP Client, MCP Tools, Profiles, API Keys, The Vault, Calendar, Refusals and Errors), e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. Cada comando, cabeçalho e mensagem abaixo é copiado dessas páginas; as mensagens e frases citadas ficam em inglês, com a tradução ao lado. Onde elas não dizem como algo funciona, dizemos isso em vez de descrever.

Sua caixa de e-mail, sua agenda, um token do GitHub e um token do Carbon Forge podem ficar no Zaru, e o Claude Code pode alcançar todos eles por um único endereço. Os tokens ficam no Zaru, um perfil decide quais deles uma chave pode tocar, e uma chamada que enviaria ou mudaria algo espera a sua resposta no Zaru Web. Este guia percorre o caminho de zaru init até a primeira chamada retida.

Passo 1. Conecte o que suas ferramentas vão usar

Cadastre-se com Get Zaru free; ele pede só um nome e um e-mail. No Vault, a página Connections conecta uma caixa do Google, o Google Calendar, uma caixa por IMAP e SMTP, ou uma agenda por CalDAV. Um token do GitHub ou um token MCP do Carbon Forge é guardado com New Credential. A documentação é clara sobre o valor: "No agent, operator, API key or other person is given the value." (Nenhum agente, operador, chave de API ou outra pessoa recebe o valor.)

Passo 2. Monte um perfil

Uma chave não alcança nada até você dizer o que ela pode alcançar. A página API Keys diz isso acima da lista: "A key reaches only the connections in the profile you choose for it; with no profile it reaches none." (Uma chave alcança só as conexões do perfil que você escolhe para ela; sem perfil, não alcança nenhuma.) Monte um perfil com as conexões e ferramentas que o editor deve ter; Dê a cada execução do Zaru só as conexões de que ela precisa percorre o formulário.

Passo 3. Crie uma chave de API e escolha o perfil dela

Abra Settings → API Keys, clique em New API Key, dê um nome, escolha uma predefinição de escopo, escolha o perfil da chave (None é o padrão), escolha uma validade e clique em Create. "The key value is shown once." (O valor da chave é mostrado uma única vez.)

Passo 4. Adicione o endpoint ao Claude Code

Todo cliente se conecta a um único endereço, https://mcp.myzaru.com/mcp/v1, por StreamableHTTP, com a chave como token Bearer. Para o Claude Code, a documentação dá:

claude mcp add zaru \
  --transport http \
  https://mcp.myzaru.com/mcp/v1 \
  --header "Authorization: Bearer YOUR_API_KEY"

A mesma página dá a configuração para Claude Desktop, Cursor, Windsurf, VS Code (GitHub Copilot) e Gemini CLI, e para qualquer cliente que fale StreamableHTTP.

Passo 5. Digite zaru init

Na sessão, diga ao assistente:

zaru init

Ele chama a ferramenta zaru.init e adota a persona do Zaru. zaru init agentic começa num modo específico. Esta é uma ferramenta do servidor MCP; o zaru init do programa de linha de comando, do guia da Zaru CLI, não tem relação com ela e não se conecta ao Zaru Web.

Passo 6. Escolha um perfil por conexão, se precisar

O perfil da chave vale para toda requisição. Em vez disso, um cliente pode enviar o cabeçalho x-zaru-contexts só com a chave reservada @profile:

x-zaru-contexts: {"@profile":"0000daeb-ae45-4d06-9712-9d498a653b24"}

Esse id é o exemplo da documentação. Numa chave, o @profile da requisição toma o lugar do perfil da própria chave para aquela requisição, e as ferramentas oferecidas passam a ser as do perfil. Qualquer outro formato recebe 400.

A página Connect Zaru to Any MCP Client mostra onde vai o cabeçalho: "Every client above sends one header, Authorization, from its configuration. The same place takes a second header, x-zaru-contexts, which chooses for every request of that connection which of your connections its tools use." (Cada cliente acima envia um cabeçalho, Authorization, a partir da sua configuração. O mesmo lugar aceita um segundo cabeçalho, x-zaru-contexts, que escolhe, para cada requisição daquela conexão, quais das suas conexões as ferramentas usam.) No Claude Code, um segundo --header:

claude mcp add zaru \
  --transport http \
  https://mcp.myzaru.com/mcp/v1 \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header 'x-zaru-contexts: {"@profile":"<profile id>"}'

Um cliente configurado por JSON (Claude Desktop, Windsurf, VS Code) o recebe como uma segunda entrada em headers. "The profile's id is the last part of the address of its page in Zaru Web, ask.myzaru.com/vault/profiles/<profile id>." (O id do perfil é a última parte do endereço da página dele no Zaru Web.) Uma coisa a documentação deixa em aberto: "Whether a given client sends a header it was configured with on every request is the client's behaviour, not documented here." (Se um cliente específico envia em toda requisição um cabeçalho com que foi configurado é comportamento do cliente, não documentado aqui.)

Passo 7. Faça uma chamada que use uma conexão

O cliente recebe a lista das ferramentas das famílias de conexão do perfil: as de e-mail para uma caixa, as de agenda para uma agenda, e as de um servidor remoto para GitHub ou Carbon Forge. Uma chamada de e-mail ou agenda que não nomeia caixa nem conta usa a única que existe, senão a mais recente, e a resposta a nomeia em mailbox_name ou account_name. Sobre as ferramentas de agenda, a documentação diz: "Your Google token or your password never reaches an agent or the model." (Seu token do Google ou sua senha nunca chegam a um agente nem ao modelo.)

A página MCP Tools os nomeia: "The remote servers a person can connect today are GitHub and Carbon Forge (formerly Nuclear Notes)." (Os servidores remotos que uma pessoa pode conectar hoje são o GitHub e o Carbon Forge, antes Nuclear Notes.) Gateways SEAL personalizados: em breve.

Passo 8. Leia uma recusa

Quando o AEGIS by 100monkeys.ai, em beta, recusa uma chamada, o cliente recebe um resultado de ferramenta comum com isError: true contendo error.code, error.message e um request_id. Duas recusas tratam de alcance:

CREDENTIAL_BINDING_REQUIRED, antes de qualquer coisa rodar. Numa chave sem perfil: "This key reaches none of your connections. Choose a profile for it on the API keys page in Zaru Web, or name one in the request." (Esta chave não alcança nenhuma das suas conexões. Escolha um perfil para ela na página de chaves de API do Zaru Web, ou nomeie um na requisição.) Para uma família que você nunca conectou, a resposta nomeia a página Connections.
TOOL_NOT_IN_PROFILE: "This tool is not in the profile chosen for this conversation." (Esta ferramenta não está no perfil escolhido para esta conversa.)

Cada uma traz error.needs, a família e a página do Zaru Web que resolve. Para uma execução, o cartão do Zaru Web diz "This run has no profile that names your <family>." (Esta execução não tem um perfil que nomeie sua <family>.) com Open Profiles. Uma recusa de política é determinística, então mude a chamada em vez de repeti-la.

Passo 9. Responda a uma chamada retida no Zaru Web

"Every tool that asks for approval waits at the person's approval gate, as a call from the chat does." (Toda ferramenta que pede aprovação espera no portão de aprovação da pessoa, como faz uma chamada vinda do chat.) A chamada responde {"status": "approval_pending", "approval_id", "summary", "message"}, cuja mensagem é "This waits for your answer in Zaru Web, under Approvals." (Isto espera sua resposta no Zaru Web, em Approvals.) Responda na página Approvals; aegis.approval.status lê a sua resposta a partir do cliente.

A página MCP Tools lista quais chamadas esperam por padrão no myzaru.com. O catálogo de ferramentas marca mail.send, mail.reply, mail.forward, mail.delete e mail.archive, e as quatro escritas de agenda, calendar.create, calendar.update, calendar.delete e calendar.respond. A configuração da implantação marca quatro escritas do GitHub, github.merge_pull_request, github.push_files, github.create_or_update_file e github.delete_file, além de aegis.git.push e aegis.system.info. "No Carbon Forge tool waits: neither the catalogue nor the configuration marks one, so a Carbon Forge call the key's profile admits runs at once." (Nenhuma ferramenta do Carbon Forge espera: nem o catálogo nem a configuração marca alguma, então uma chamada do Carbon Forge que o perfil da chave admite roda na hora.) O formulário do perfil marca cada ferramenta que espera com "Needs your approval" (Precisa da sua aprovação). Uma escolha permanente "Always allow" (Sempre permitir) responde às chamadas dela sem perguntar, então a espera é o padrão, não uma promessa.

Guias relacionados

Coloque todas as suas ferramentas MCP atrás de um único endpoint. Estamos sempre ampliando a biblioteca de ferramentas MCP: peça novas ferramentas por e-mail para [email protected].

Get Zaru free