MCP

Configura Claude Desktop

Sonenta include un server MCP nativo così che qualsiasi client MCP-compatibile — Claude Desktop, Cursor, il tuo agente — possa cercare chiavi, proporre traduzioni, revisionare PR e ispezionare la coda delle chiavi mancanti. Due righe di config, il tuo token, fatto.

1. Ottieni una API key

Nella tua dashboard, vai a Org Settings → API Keys → Create. Assegnale lo scope mcp:* (copre tutti e cinque i tool sotto). Il secret è mostrato una volta sola; copia l'intera stringa vrb_live_<prefix>.<secret>.

Conservala nel keychain del tuo OS o in un .env locale — non committarla mai. La key è legata alla tua org (e opzionalmente a un progetto); le chiamate fuori scope restituiscono 404. Revoca dalla dashboard quando vuoi; le key revocate rispondono 401 alla chiamata successiva.

2. Installa (o salta)

Il server MCP è pubblicato su npm e Homebrew. Con npx non devi installare nulla — Claude Desktop tira l'ultima versione a ogni avvio. Con brew ottieni un binario locale fissato, utile dietro firewall restrittivi.

npx (consigliato)

1// nessuna installazione — npx tira l'ultimo @sonenta/mcp on demand2npx -y @sonenta/mcp --version

Homebrew (alternativa) Tap pubblicato al lancio V1

1// opzionale: installa globalmente una volta — arriva al lancio V12brew install sonenta/tap/sonenta-mcp

3. Collega Claude Desktop

Apri il file di config di Claude Desktop, aggiungi la voce verbumia sotto mcpServers, poi chiudi e rilancia l'app.

claude_desktop_config.json

1// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json2// Windows: %APPDATA%/Claude/claude_desktop_config.json3{4  "mcpServers": {5    "sonenta": {6      "command": "npx",7      "args": ["-y", "@sonenta/mcp"],8      "env": {9        "SONENTA_API_KEY": "vrb_live_<prefix>.<secret>",10        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"11      }12    }13  }14}

Tre variabili d'ambiente in totale: SONENTA_TOKEN (obbligatoria), SONENTA_PROJECT (opzionale — pre-imposta un progetto così l'agente non deve chiamare prima list_projects) e SONENTA_API_BASE (opzionale — default https://api.sonenta.com; sovrascrivi per self-hosted o staging).

SONENTA_PROJECTS requires @sonenta/mcp ≥ 0.11.0. On older releases, see Backwards compatibility below.

Multi-project tool calls

When SONENTA_PROJECTS lists more than one UUID, the agent can't infer which project you mean — every tool call must include project_uuid. With a single UUID (or only the legacy SONENTA_PROJECT set), it's optional and defaults to that project.

tools/call arguments

1// list_missing_keys — project_uuid is REQUIRED when SONENTA_PROJECTS lists more than one UUID2{3  "name": "list_missing_keys",4  "arguments": {5    "project_uuid": "<uuid1>",6    "namespace": "checkout",7    "language_code": "ja"8  }9}

Phrase your prompt with the project in mind (« in the Checkout project, list missing keys for ja ») — the agent will resolve the project to its UUID and pass project_uuid on the tool call. For ambiguous prompts across multiple projects, the agent will call list_projects first.

Cursor (e altri client MCP)

Stesso JSON, file diverso. In Cursor, mettilo in .cursor/mcp.json (scope progetto) o ~/.cursor/mcp.json (scope utente). Per altri client, segui la doc di configurazione MCP del tuo client — la voce mcpServers.verbumia è identica.

.cursor/mcp.json

1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "sonenta": {5      "command": "npx",6      "args": ["-y", "@sonenta/mcp"],7      "env": { "SONENTA_API_KEY": "vrb_live_<prefix>.<secret>" }8    }9  }10}

I 5 tool V1

Una volta configurato, l'agente ha questi tool a disposizione. Non li chiami per nome — descrivi la tua intenzione in chat e l'agente sceglie. I nomi sotto sono gli identificatori canonici, utili per leggere le tracce dell'agente o costruire agenti custom sopra lo stesso server.

list_projects Enumera i progetti a cui la API key corrente ha accesso. Utile per scegliere un workspace all'inizio di una chat.

Args

limit number limite opzionale sul numero di progetti restituiti

Prompt di esempio

"Elenca i miei progetti Sonenta."

get_project_info Recupera i metadata del progetto: lingua sorgente, lingue target, namespace, conteggio totale chiavi.

Args

project_uuid string required

Prompt di esempio

"Quali lingue e namespace ship il progetto Checkout?"

list_missing_keys Elenca gli eventi pendenti di chiavi mancanti catturati dall'SDK runtime (paginato per cursor). Filtra per namespace o lingua.

Args

project_uuid string required
namespace string limita a un namespace (es. "checkout")
language_code string limita a una lingua (es. "ja")
cursor string cursor di paginazione restituito da una chiamata precedente
limit number dimensione pagina (default 20)

Prompt di esempio

"Quali chiavi di traduzione mancano per ja nel namespace checkout?"

propose_translation Invia un valore di traduzione per una chiave in una lingua target. Sempre scritto come draft; un reviewer umano lo promuove dopo — Sonenta è il manager, non il motore.

Args

project_uuid string required
key string required
namespace string required
language_code string required
value string required

Prompt di esempio

"Proponi \"Confirmer la commande\" per checkout.review.confirm in fr-CA."

validate_translations Linta un payload JSON i18next prima del push: parità dei placeholder ICU, chiavi mancanti/in eccesso, drift di tipo tra locali.

Args

project_uuid string required
language_code string required
payload object required mappa di traduzioni in forma JSON i18next

Prompt di esempio

"Valida questo file di traduzione contro la sorgente inglese del progetto."

Plan limits & quotas

You pay when an agent mutates your project, not when it observes it. Reads and listings are free; writes burn one unit; bulk and AI-assisted ops scale with the work they do.

What counts as a billable call

Reads — free

list_missing, list_keys, get_translation, search, plus auth / discover / meta. Browse the missing-key queue all day — it never touches your quota.

Writes — 1 unit

Each set / create / update / delete on a key or translation costs one unit, regardless of payload size.

Bulk — 1 unit per key

Multi-key endpoints (e.g. acknowledge) bill per key touched: a 50-key acknowledge debits 50 units, with rollback on partial-reject.

AI / auto-translate — ×5

Calls that invoke an LLM (auto-translate, AI Quality Review, suggest) bill 5 units per call. Higher weight reflects model cost.

Per-plan ceilings

Monthly quota, hard per-minute rate, concurrent MCP sessions, and whether writes are allowed. The same numbers feed the X-MCP-Quota-Remaining header on every response.

Plan	Units / month	Rate	Sessions	Writes
Free	NaN	NaNreq/min	NaN	blocked
Hobby	NaN	NaNreq/min	NaN	blocked
Pro	NaN	NaNreq/min	NaN	blocked
Team	NaN	NaNreq/min	NaN	blocked

When you hit a ceiling

Over the per-minute rate → 429 mcp_rate_limited with Retry-After (seconds). Over the monthly quota → 429 mcp_quota_exceeded with Retry-After set to the rollover. Free plan writes → 403 mcp_writes_disabled. Quotas reset on the 1st of each calendar month, UTC.

Verifica che funzioni

1 Riavvia Claude Desktop completamente (chiudi, rilancia — la config viene letta all'avvio).
2 Apri una nuova chat. L'icona del martello deve mostrare verbumia con 5 tool disponibili.
3 Scrivi "List my Sonenta projects." L'agente dovrebbe chiamare list_projects e restituire i tuoi workspace.

Bloccato? Controlla i log di Claude Desktop in ~/Library/Logs/Claude/mcp*.log (macOS). Il 90% dei problemi sono typo nel JSON o un token scaduto.

Backwards compatibility

I nomi pre-0.4.0 SONENTA_TOKEN e SONENTA_API_BASE sono ancora accettati come fallback; l'SDK li legge in silenzio se i nomi canonici non sono impostati.

Prossimo

Avvio rapido

React + i18next

Cattura chiavi mancanti a runtime, end-to-end.

Riferimento

Tutte le docs

CLI, riferimento API (in corso).