Configurer Claude Desktop

Sonenta fournit un serveur MCP natif pour que tout client compatible MCP, Claude Desktop, Cursor, votre propre agent, puisse chercher des clés, proposer des traductions, réviser des PRs, et inspecter la file des manquantes. Deux lignes de config, votre token, c'est fait.

1. Obtenir une clé API

Dans votre dashboard, allez à Org Settings → API Keys → Create. Donnez-lui le scope mcp:* (couvre les cinq outils ci-dessous). Le secret est affiché une seule fois ; copiez l'intégralité de snt_live_<prefix>.<secret>.

Stockez-le dans le keychain de votre OS ou dans un .env local, ne le committez jamais. La clé est liée à votre org (et optionnellement à un projet) ; les appels hors scope retournent 404. Révoquez depuis le dashboard à tout moment ; les clés révoquées renvoient 401 au prochain appel.

2. Installer (ou non)

Le serveur MCP est publié sur npm et Homebrew. Avec npx vous n'avez rien à installer, Claude Desktop tire la dernière version à chaque lancement. Avec brew vous obtenez un binaire local figé, utile derrière des firewalls stricts.

npx (recommandé)

# pas d'installation - npx tire la dernière version de @sonenta/mcp à la demande
npx -y @sonenta/mcp --version

Homebrew (alternative)

# optionnel : installer une fois globalement
brew install sonenta/tap/sonenta-mcp

3. Brancher Claude Desktop

Ouvrez le fichier de config de Claude Desktop, ajoutez l'entrée sonenta sous mcpServers, puis quittez et relancez l'app.

// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "sonenta": {
      "command": "npx",
      "args": ["-y", "@sonenta/mcp"],
      "env": {
        "SONENTA_API_KEY": "snt_live_<prefix>.<secret>",
        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"
      }
    }
  }
}

Trois variables d'environnement au total : SONENTA_API_KEY (obligatoire, la clé API depuis votre dashboard), SONENTA_PROJECTS (optionnel, liste CSV d'UUID de projets, avec un seul UUID l'agent n'a pas besoin d'appeler list_projects ; avec plusieurs UUID, chaque appel d'outil doit passer project_uuid pour lever l'ambiguïté), et SONENTA_BASE_URL (optionnel, défaut https://api.sonenta.com ; override pour self-host ou staging).

Appels d'outils multi-projets

Quand SONENTA_PROJECTS liste plus d'un UUID, l'agent ne peut pas deviner de quel projet vous parlez, chaque appel d'outil doit inclure project_uuid. Avec un seul UUID (ou uniquement le legacy SONENTA_PROJECT), c'est optionnel et l'appel défaut sur ce projet.

// list_missing_keys - project_uuid is REQUIRED when SONENTA_PROJECTS lists more than one UUID
{
  "name": "list_missing_keys",
  "arguments": {
    "project_uuid": "<uuid1>",
    "namespace": "checkout",
    "language_code": "ja"
  }
}

Formulez votre prompt en nommant le projet (« dans le projet Checkout, liste les clés manquantes en ja »), l'agent résoudra le projet vers son UUID et passera project_uuid sur l'appel d'outil. Pour un prompt ambigu entre plusieurs projets, l'agent appellera list_projects d'abord.

Cursor (et autres clients MCP)

Même JSON, fichier différent. Dans Cursor, déposez-le dans .cursor/mcp.json (scope projet) ou ~/.cursor/mcp.json (scope utilisateur). Pour les autres clients, suivez la doc de config MCP de votre client, l'entrée mcpServers.sonenta est identique.

// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)
{
  "mcpServers": {
    "sonenta": {
      "command": "npx",
      "args": ["-y", "@sonenta/mcp"],
      "env": { "SONENTA_API_KEY": "snt_live_<prefix>.<secret>" }
    }
  }
}

Les 5 outils

Une fois configuré, l'agent dispose de ces outils. Vous ne les appelez pas par nom, décrivez votre intention en chat et l'agent choisit. Les noms ci-dessous sont les identifiants canoniques, utiles pour lire les traces d'agent ou construire vos propres agents sur le même serveur.

`list_projects`

Énumère les projets accessibles à la clé API courante. Utile pour choisir un workspace en début de chat.

Args

limit number : limite optionnelle sur le nombre de projets retournés

Exemple de prompt : « Liste mes projets Sonenta. »

`get_project_info`

Récupère les métadonnées du projet : langue source, langues cibles, namespaces, nombre total de clés.

Args

project_uuid string, requis

Exemple de prompt : « Quelles langues et namespaces ship le projet Checkout ? »

`list_missing_keys`

Liste les événements de clés manquantes capturés par le SDK runtime (paginé par cursor). Filtrable par namespace ou langue.

Args

project_uuid string, requis
namespace string : limite à un namespace (ex. « checkout »)
language_code string : limite à une langue (ex. « ja »)
cursor string : cursor de pagination retourné par un appel précédent
limit number : taille de page (défaut 20)

Exemple de prompt : « Quelles clés de traduction manquent pour ja dans le namespace checkout ? »

`propose_translation`

Soumet une valeur de traduction pour une clé dans une langue cible. Toujours écrit en draft ; un reviewer humain promeut plus tard, Sonenta est le gestionnaire, pas le moteur.

Args

project_uuid string, requis
key string, requis
namespace string, requis
language_code string, requis
value string, requis

Exemple de prompt : « Propose "Confirmer la commande" pour checkout.review.confirm en fr-CA. »

`validate_translations`

Lint d'un payload JSON i18next avant push : parité des placeholders ICU, clés manquantes/superflues, dérive de type entre locales.

Args

project_uuid string, requis
language_code string, requis
payload object, requis : map de traductions au format JSON i18next

Exemple de prompt : « Valide ce fichier de traduction contre la source anglaise du projet. »

Limites & quotas par plan

Vous payez quand un agent modifie votre projet, pas quand il l'observe. Les lectures et les listes sont gratuites ; les écritures coûtent une unité ; le bulk et les appels assistés par IA s'échelonnent avec le travail effectué.

Ce qui compte comme appel facturable

Lectures, gratuites : list_missing, list_keys, get_translation, search, plus auth / discover / meta. Parcourez la file des clés manquantes toute la journée, votre quota n'y touche pas.

Écritures, 1 unité : Chaque set / create / update / delete sur une clé ou une traduction coûte une unité, peu importe la taille du payload.

Bulk, 1 unité par clé : Les endpoints multi-clés (ex. acknowledge) facturent par clé touchée : un acknowledge de 50 clés débite 50 unités, avec rollback en cas de reject partiel.

IA / auto-translate, ×5 : Les appels qui invoquent un LLM (auto-translate, AI Quality Review, suggest) facturent 5 unités par appel. Le poids plus élevé reflète le coût du modèle.

Plafonds par plan

Quota mensuel, plafond strict par minute, sessions MCP concurrentes, et autorisation d'écriture. Les mêmes valeurs alimentent l'en-tête X-MCP-Quota-Remaining sur chaque réponse.

Plan	Unités / mois	Cadence	Sessions	Écritures
Free	500	10 req/min	1	bloquées
Hobby	5 000	30 req/min	2	autorisées
Pro	50 000	120 req/min	10	autorisées
Team	250 000	600 req/min	50	autorisées

Quand vous atteignez un plafond

Au-dessus de la cadence par minute → 429 mcp_rate_limited avec Retry-After (secondes). Au-dessus du quota mensuel → 429 mcp_quota_exceeded avec Retry-After calé sur le rollover. Écritures sur le plan Free → 403 mcp_writes_disabled. Les quotas se réinitialisent le 1ᵉʳ de chaque mois calendaire, UTC.

Vérifier que ça marche

Redémarrez Claude Desktop complètement (quittez, relancez, la config est lue au démarrage).
Ouvrez un nouveau chat. L'icône marteau doit montrer sonenta avec 5 outils disponibles.
Tapez « List my Sonenta projects. » L'agent devrait appeler list_projects et retourner vos workspaces.

Bloqué ? Consultez les logs de Claude Desktop dans ~/Library/Logs/Claude/mcp*.log (macOS). 90 % des problèmes sont des typos dans le JSON ou un token périmé.

Ensuite

Démarrage rapide : React + i18next : Capturer les clés manquantes en runtime, de bout en bout. /docs-next/getting-started/installation/
Référence : Toutes les docs : CLI, référence API (en cours). /docs-next/

Référence des outils

La liste complète des outils MCP, avec leurs arguments : voir la référence MCP.