Configurar Claude Desktop

1. Obtén una API key

En tu dashboard, ve a Org Settings → API Keys → Create. Asígnale el scope mcp:* (cubre las cinco herramientas de abajo). El secret se muestra una sola vez; copia la cadena completa vrb_live_<prefix>.<secret>.

Guárdala en el llavero del SO o en un .env local — nunca la commitees. La key está ligada a tu org (y opcionalmente a un proyecto); las llamadas fuera de ese scope devuelven 404. Revoca desde el dashboard cuando quieras; las keys revocadas devuelven 401 en la siguiente llamada.

2. Instala (o sáltatelo)

El servidor MCP se publica en npm y Homebrew. Con npx no necesitas instalar nada — Claude Desktop tira de la última versión en cada arranque. Con brew obtienes un binario local fijado, útil tras firewalls estrictos.

1// sin instalación — npx tira de la última @sonenta/mcp bajo demanda2npx -y @sonenta/mcp --version

1// opcional: instalar globalmente una vez — llega con el lanzamiento V12brew install sonenta/tap/sonenta-mcp

3. Conecta Claude Desktop

Abre el archivo de config de Claude Desktop, añade la entrada verbumia bajo mcpServers, luego cierra y vuelve a abrir la 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": "vrb_live_<prefix>.<secret>",10        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"11      }12    }13  }14}

Tres variables de entorno en total: SONENTA_TOKEN (obligatoria), SONENTA_PROJECT (opcional — pre-fija un proyecto para que el agente no tenga que llamar a list_projects primero) y SONENTA_API_BASE (opcional — por defecto https://api.sonenta.com; sobrescríbela para 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.

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 (y otros clientes MCP)

Mismo JSON, archivo distinto. En Cursor, ponlo en .cursor/mcp.json (scope de proyecto) o ~/.cursor/mcp.json (scope de usuario). Para otros clientes, sigue la doc de configuración MCP de tu cliente — la entrada mcpServers.verbumia es 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": "vrb_live_<prefix>.<secret>" }8    }9  }10}

Las 5 herramientas V1

Una vez configurado, el agente dispone de estas herramientas. No las llamas por nombre — describe tu intención en el chat y el agente las elige. Los nombres de abajo son los identificadores canónicos, útiles al leer trazas del agente o construir agentes propios sobre el mismo servidor.

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

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.

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.

Verificar que funciona

1. 1 Reinicia Claude Desktop completamente (cierra, relanza — la config se lee al arranque).
2. 2 Abre un chat nuevo. El icono del martillo debe mostrar verbumia con 5 herramientas disponibles.
3. 3 Escribe "List my Sonenta projects." El agente debería llamar a list_projects y devolver tus workspaces.

¿Atascado? Revisa los logs de Claude Desktop en ~/Library/Logs/Claude/mcp*.log (macOS). El 90% de los problemas son typos en el JSON o un token caducado.