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 snt_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 sonenta 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": "snt_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.dev; sobrescríbela para self-hosted o staging).

SONENTA_PROJECTS requiere @sonenta/mcp ≥ 0.11.0. En versiones anteriores, ver Retrocompatibilidad más abajo.

Llamadas de herramienta multiproyecto

Cuando SONENTA_PROJECTS lista más de un UUID, el agente no puede adivinar de qué proyecto hablas, cada llamada de herramienta debe incluir project_uuid. Con un solo UUID (o únicamente el legacy SONENTA_PROJECT), es opcional y la llamada usa ese proyecto por defecto.

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}

Formula tu prompt nombrando el proyecto («en el proyecto Checkout, lista las claves faltantes en ja»), el agente resolverá el proyecto hacia su UUID y pasará project_uuid en la llamada de herramienta. Para un prompt ambiguo entre varios proyectos, el agente llamará primero a list_projects.

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.sonenta 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": "snt_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.

Límites y cuotas por plan

Pagas cuando un agente modifica tu proyecto, no cuando lo observa. Las lecturas y los listados son gratis; las escrituras consumen una unidad; las operaciones en bulk y asistidas por IA escalan con el trabajo que realizan.

Lo que cuenta como llamada facturable

Topes por plan

Cuota mensual, tope estricto por minuto, sesiones MCP concurrentes y si se permiten las escrituras. Los mismos valores alimentan la cabecera X-MCP-Quota-Remaining en cada respuesta.

Cuando alcanzas un tope

Por encima de la cadencia por minuto → 429 mcp_rate_limited con Retry-After (segundos). Por encima de la cuota mensual → 429 mcp_quota_exceeded con Retry-After ajustado al rollover. Escrituras en el plan Free → 403 mcp_writes_disabled. Las cuotas se reinician el 1.º de cada mes natural, 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 sonenta 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.