Un endpoint Zaru per i vostri strumenti, profili e approvazioni

Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano

Trasparenza: Zaru è sviluppato da 100monkeys AI, Inc., quindi leggete questa guida come il resoconto di chi lo costruisce. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione di Zaru, letta il 29 ottobre 2026 (Connect Zaru to Any MCP Client, MCP Tools, Profiles, API Keys, The Vault, Calendar, Refusals and Errors), e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Ogni comando, header e messaggio qui sotto è copiato da quelle pagine; le citazioni restano in inglese, con la traduzione accanto. Dove non dicono come funziona qualcosa, lo diciamo invece di descriverlo.

La vostra casella di posta, il vostro calendario, un token GitHub e un token Carbon Forge possono stare in Zaru, e Claude Code può raggiungerli tutti da un solo indirizzo. I token restano in Zaru, un profilo decide quali una chiave può toccare, e una chiamata che invierebbe o cambierebbe qualcosa aspetta la vostra risposta in Zaru Web. Questa guida va da zaru init fino alla prima chiamata in attesa.

Passo 1. Collegate ciò che useranno i vostri strumenti

Registratevi con Get Zaru free (Prova Zaru gratis); chiede solo un nome e un indirizzo e-mail. Nel Vault, la pagina Connections collega una casella Google, Google Calendar, una casella via IMAP e SMTP, o un calendario via CalDAV. Un token GitHub o un token MCP di Carbon Forge si salva con New Credential. Sul valore la documentazione è chiara: "No agent, operator, API key or other person is given the value." (Nessun agente, operatore, chiave API o altra persona riceve il valore.)

Passo 2. Create un profilo

Una chiave non raggiunge nulla finché non dite che cosa può raggiungere. La pagina API Keys lo dice sopra il suo elenco: "A key reaches only the connections in the profile you choose for it; with no profile it reaches none." (Una chiave raggiunge solo le connessioni del profilo che scegliete per lei; senza profilo non ne raggiunge nessuna.) Create un profilo con le connessioni e gli strumenti che l'editor deve avere; Date a ogni esecuzione di Zaru solo le connessioni utili percorre il modulo.

Passo 3. Create una chiave API e sceglietene il profilo

Aprite Settings → API Keys, premete New API Key, datele un nome, scegliete un preset di ambito, scegliete il profilo della chiave (None è il predefinito), scegliete una scadenza e premete Create. "The key value is shown once." (Il valore della chiave viene mostrato una sola volta.)

Passo 4. Aggiungete l'endpoint a Claude Code

Ogni client si collega a un solo indirizzo, https://mcp.myzaru.com/mcp/v1, via StreamableHTTP, con la chiave come token Bearer. Per Claude Code la documentazione dà:

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

La stessa pagina dà la configurazione per Claude Desktop, Cursor, Windsurf, VS Code (GitHub Copilot) e Gemini CLI, e per qualsiasi client che parli StreamableHTTP.

Passo 5. Scrivete zaru init

Nella sessione, dite all'assistente:

zaru init

Chiama lo strumento zaru.init e adotta la persona di Zaru. zaru init agentic parte in una modalità precisa. È uno strumento del server MCP; lo zaru init del programma a riga di comando, dalla guida alla Zaru CLI, non c'entra e non si collega a Zaru Web.

Passo 6. Scegliete un profilo per connessione, se serve

Il profilo della chiave vale per ogni richiesta. Un client può invece inviare l'header x-zaru-contexts con la sola chiave riservata @profile:

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

Quell'id è l'esempio della documentazione. Su una chiave, il @profile della richiesta prende il posto del profilo della chiave per quella richiesta, e gli strumenti offerti diventano quelli del profilo. Qualsiasi altra forma riceve 400.

La pagina Connect Zaru to Any MCP Client mostra dove va l'header: "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." (Ogni client qui sopra invia un header, Authorization, dalla propria configurazione. Lo stesso punto accetta un secondo header, x-zaru-contexts, che sceglie, per ogni richiesta di quella connessione, quali delle vostre connessioni usano i suoi strumenti.) In Claude Code, un secondo --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>"}'

Un client configurato via JSON (Claude Desktop, Windsurf, VS Code) lo riceve come seconda voce sotto 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>." (L'id del profilo è l'ultima parte dell'indirizzo della sua pagina in Zaru Web.) Una cosa la documentazione la lascia aperta: "Whether a given client sends a header it was configured with on every request is the client's behaviour, not documented here." (Se un dato client invia a ogni richiesta un header con cui è stato configurato dipende dal comportamento del client, non documentato qui.)

Passo 7. Fate una chiamata che usa una connessione

Al client vengono elencati gli strumenti delle famiglie di connessione del profilo: quelli di posta per una casella, quelli di calendario per un calendario, e quelli di un server remoto per GitHub o Carbon Forge. Una chiamata di posta o calendario che non nomina casella né account usa l'unico presente, altrimenti il più recente, e la risposta lo nomina in mailbox_name o account_name. Degli strumenti di calendario la documentazione dice: "Your Google token or your password never reaches an agent or the model." (Il vostro token Google o la vostra password non raggiungono mai un agente o il modello.)

La pagina MCP Tools li nomina: "The remote servers a person can connect today are GitHub and Carbon Forge (formerly Nuclear Notes)." (I server remoti che una persona può collegare oggi sono GitHub e Carbon Forge, già Nuclear Notes.) Gateway SEAL personalizzati: in arrivo.

Passo 8. Leggete un rifiuto

Quando AEGIS by 100monkeys.ai, in beta, rifiuta una chiamata, il client riceve un normale risultato di strumento con isError: true che contiene error.code, error.message e un request_id. Due rifiuti riguardano la portata:

CREDENTIAL_BINDING_REQUIRED, prima che parta qualsiasi cosa. Su una chiave senza profilo: "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." (Questa chiave non raggiunge nessuna delle vostre connessioni. Sceglietele un profilo nella pagina delle chiavi API di Zaru Web, o nominatene uno nella richiesta.) Per una famiglia che non avete mai collegato, la risposta nomina la pagina Connections.
TOOL_NOT_IN_PROFILE: "This tool is not in the profile chosen for this conversation." (Questo strumento non è nel profilo scelto per questa conversazione.)

Ognuno porta error.needs, la famiglia e la pagina di Zaru Web che risolve. Per un'esecuzione, la scheda di Zaru Web dice "This run has no profile that names your <family>." (Questa esecuzione non ha un profilo che nomini la vostra <family>.) con Open Profiles. Un rifiuto di policy è deterministico, quindi cambiate la chiamata invece di ripeterla.

Passo 9. Rispondete in Zaru Web a una chiamata in attesa

"Every tool that asks for approval waits at the person's approval gate, as a call from the chat does." (Ogni strumento che chiede approvazione aspetta al cancello di approvazione della persona, come fa una chiamata dalla chat.) La chiamata risponde {"status": "approval_pending", "approval_id", "summary", "message"}, il cui messaggio è "This waits for your answer in Zaru Web, under Approvals." (Questo aspetta la vostra risposta in Zaru Web, sotto Approvals.) Rispondete nella pagina Approvals; aegis.approval.status legge la vostra risposta dal client.

La pagina MCP Tools elenca quali chiamate aspettano per impostazione predefinita su myzaru.com. Il catalogo degli strumenti segna mail.send, mail.reply, mail.forward, mail.delete e mail.archive, e le quattro scritture di calendario, calendar.create, calendar.update, calendar.delete e calendar.respond. La configurazione del deployment segna quattro scritture di GitHub, github.merge_pull_request, github.push_files, github.create_or_update_file e github.delete_file, oltre a 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." (Nessuno strumento di Carbon Forge aspetta: né il catalogo né la configurazione ne segna uno, quindi una chiamata di Carbon Forge che il profilo della chiave ammette parte subito.) Il modulo del profilo segna ogni strumento che aspetta con "Needs your approval" (Richiede la vostra approvazione). Una scelta permanente "Always allow" (Consenti sempre) risponde alle sue chiamate senza chiedere, quindi l'attesa è il comportamento predefinito, non una promessa.

Guide correlate

Mettete tutti i vostri strumenti MCP dietro un solo endpoint. Ampliamo di continuo la libreria di strumenti MCP: chiedete nuovi strumenti scrivendo a [email protected].

Prova Zaru gratis