Configurar o Claude Desktop

1. Obtém uma API key

No teu dashboard, vai a Org Settings → API Keys → Create. Atribui-lhe o scope mcp:* (cobre as cinco ferramentas abaixo). O secret é mostrado uma única vez; copia a string completa snt_live_<prefix>.<secret>.

Guarda-a no keychain do teu SO ou num .env local — nunca a faças commit. A key está ligada à tua org (e opcionalmente a um projeto); chamadas fora desse scope devolvem 404. Revoga a partir do dashboard quando quiseres; keys revogadas devolvem 401 na chamada seguinte.

2. Instala (ou salta)

O servidor MCP é publicado no npm e no Homebrew. Com npx não precisas de instalar nada — o Claude Desktop puxa a versão mais recente a cada arranque. Com brew obténs um binário local fixo, útil atrás de firewalls restritivos.

1// sem instalação — npx puxa o último @sonenta/mcp a pedido2npx -y @sonenta/mcp --version

1// opcional: instala globalmente uma vez — chega com o lançamento V12brew install sonenta/tap/sonenta-mcp

3. Liga o Claude Desktop

Abre o ficheiro de config do Claude Desktop, adiciona a entrada sonenta sob mcpServers, depois fecha e relança a 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}

Três variáveis de ambiente no total: SONENTA_TOKEN (obrigatória), SONENTA_PROJECT (opcional — pré-define um projeto para que o agente não tenha de chamar list_projects primeiro) e SONENTA_API_BASE (opcional — por defeito https://api.sonenta.com; sobrescreve para self-hosted ou staging).

SONENTA_PROJECTS requer @sonenta/mcp ≥ 0.11.0. Em releases mais antigas, veja Retrocompatibilidade mais abaixo.

Chamadas de ferramentas multiprojeto

Quando SONENTA_PROJECTS lista mais do que um UUID, o agente não consegue inferir de que projeto fala — cada chamada de ferramenta tem de incluir project_uuid. Com um único UUID (ou apenas o legado SONENTA_PROJECT definido), é opcional e a chamada assume por omissão esse projeto.

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}

Formule o seu prompt com o projeto em mente («no projeto Checkout, lista as chaves em falta em ja») — o agente resolverá o projeto para o seu UUID e passará project_uuid na chamada de ferramenta. Para um prompt ambíguo entre vários projetos, o agente chamará list_projects primeiro.

Cursor (e outros clientes MCP)

Mesmo JSON, ficheiro diferente. No Cursor, coloca-o em .cursor/mcp.json (scope de projeto) ou ~/.cursor/mcp.json (scope de utilizador). Para outros clientes, segue a doc de configuração MCP do teu cliente — a entrada mcpServers.sonenta é idêntica.

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}

As 5 ferramentas V1

Uma vez configurado, o agente tem estas ferramentas disponíveis. Não as chamas por nome — descreve a tua intenção no chat e o agente escolhe. Os nomes abaixo são os identificadores canónicos, úteis ao ler traces do agente ou ao construir agentes próprios sobre o mesmo servidor.

Limites e quotas por plano

Paga quando um agente modifica o seu projeto, não quando o observa. As leituras e listagens são gratuitas; as escritas consomem uma unidade; o bulk e as operações assistidas por IA escalam com o trabalho que realizam.

O que conta como chamada faturável

Limites por plano

Quota mensal, limite rígido por minuto, sessões MCP concorrentes e se as escritas são permitidas. Os mesmos valores alimentam o cabeçalho X-MCP-Quota-Remaining em cada resposta.

Quando atinge um limite

Acima da cadência por minuto → 429 mcp_rate_limited com Retry-After (segundos). Acima da quota mensal → 429 mcp_quota_exceeded com Retry-After ajustado ao rollover. Escritas no plano Free → 403 mcp_writes_disabled. As quotas reiniciam no dia 1 de cada mês de calendário, UTC.

Verificar que funciona

1. 1 Reinicia o Claude Desktop por completo (sai, relança — a config é lida no arranque).
2. 2 Abre um novo chat. O ícone do martelo deve mostrar sonenta com 5 ferramentas disponíveis.
3. 3 Escreve "List my Sonenta projects." O agente deve chamar list_projects e devolver os teus workspaces.

Empancado? Verifica os logs do Claude Desktop em ~/Library/Logs/Claude/mcp*.log (macOS). 90% dos problemas são typos no JSON ou um token caducado.