Configurer Claude Desktop

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.

1// pas d'installation, npx tire la dernière version de @sonenta/mcp à la demande2npx -y @sonenta/mcp --version

1// optionnel : installer une fois globalement, arrive au lancement V12brew 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.

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": "snt_live_<prefix>.<secret>",10        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"11      }12    }13  }14}

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.dev ; override pour self-host ou staging).

SONENTA_PROJECTS nécessite @sonenta/mcp ≥ 0.11.0. Pour les versions antérieures, voir Rétrocompatibilité plus bas.

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.

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}

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.

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": "snt_live_<prefix>.<secret>" }8    }9  }10}

Les 5 outils V1

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.

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

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.

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

1. 1 Redémarrez Claude Desktop complètement (quittez, relancez, la config est lue au démarrage).
2. 2 Ouvrez un nouveau chat. L'icône marteau doit montrer sonenta avec 5 outils disponibles.
3. 3 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é.