Configura Claude Desktop

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 snt_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.

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

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 sonenta sotto mcpServers, poi chiudi e rilancia 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}

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 richiede @sonenta/mcp ≥ 0.11.0. Sulle versioni precedenti, vedi Retrocompatibilità più sotto.

Chiamate di strumenti multi-progetto

Quando SONENTA_PROJECTS elenca più di un UUID, l'agente non può indovinare di quale progetto state parlando — ogni chiamata di strumento deve includere project_uuid. Con un solo UUID (o solo il legacy SONENTA_PROJECT), è opzionale e la chiamata usa per impostazione predefinita quel progetto.

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}

Formulate il vostro prompt nominando il progetto («nel progetto Checkout, elenca le chiavi mancanti in ja») — l'agente risolverà il progetto verso il suo UUID e passerà project_uuid sulla chiamata di strumento. Per un prompt ambiguo tra più progetti, l'agente chiamerà prima list_projects.

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.sonenta è identica.

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}

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.

Limiti e quote per piano

Pagate quando un agente modifica il vostro progetto, non quando lo osserva. Le letture e gli elenchi sono gratuiti; le scritture consumano un'unità; le operazioni bulk e assistite dall'IA si scalano con il lavoro svolto.

Cosa conta come chiamata fatturabile

Tetti per piano

Quota mensile, tetto rigido al minuto, sessioni MCP concorrenti e autorizzazione alla scrittura. Gli stessi valori alimentano l'header X-MCP-Quota-Remaining su ogni risposta.

Quando raggiungete un tetto

Oltre la cadenza al minuto → 429 mcp_rate_limited con Retry-After (secondi). Oltre la quota mensile → 429 mcp_quota_exceeded con Retry-After impostato sul rollover. Scritture sul piano Free → 403 mcp_writes_disabled. Le quote si reimpostano il 1º di ogni mese di calendario, UTC.

Verifica che funzioni

1. 1 Riavvia Claude Desktop completamente (chiudi, rilancia — la config viene letta all'avvio).
2. 2 Apri una nuova chat. L'icona del martello deve mostrare sonenta con 5 tool disponibili.
3. 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.