MCP

Настрой Claude Desktop

Sonenta поставляется со встроенным MCP сервером, чтобы любой MCP-клиент, Claude Desktop, Cursor, твой собственный агент, мог искать ключи, предлагать переводы, ревьюить PR'ы и смотреть очередь missing-keys. Две строки конфига, твой токен, готово.

1. Получи API-ключ

В дашборде перейди в Org Settings → API Keys → Create. Дай ему scope mcp:* (покрывает все пять инструментов ниже). Секрет показывается один раз; скопируй полную строку snt_live_<prefix>.<secret>.

Храни в keychain ОС или в локальном .env, никогда не коммить. Ключ привязан к твоей org (и опционально к одному проекту); вызовы вне этого scope возвращают 404. Отозвать можно из дашборда в любой момент; отозванные ключи отдают 401 на следующем вызове.

2. Установка (или пропусти)

MCP server опубликован в npm и Homebrew. С npx ничего ставить не нужно, Claude Desktop тянет последнюю версию при каждом запуске. С brew получаешь зафиксированный локальный бинарник, удобно за строгими firewall'ами.

npx (рекомендуется)

1// установка не нужна, npx подтягивает свежий @sonenta/mcp по требованию2npx -y @sonenta/mcp --version

Homebrew (альтернатива) Tap публикуется в V1

1// опционально: установить глобально один раз, будет к запуску V12brew install sonenta/tap/sonenta-mcp

3. Подключи Claude Desktop

Открой конфиг-файл Claude Desktop, добавь запись sonenta под mcpServers, затем закрой и перезапусти приложение.

claude_desktop_config.json

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}

Всего три env-переменные: SONENTA_TOKEN (обязательная), SONENTA_PROJECT (опциональная, заранее задаёт проект, чтобы агенту не пришлось сначала вызывать list_projects) и SONENTA_API_BASE (опциональная, по умолчанию https://api.sonenta.dev; переопредели для self-hosted или staging).

SONENTA_PROJECTS требует @sonenta/mcp ≥ 0.11.0. Для более ранних релизов см. Обратную совместимость ниже.

Вызовы инструментов в нескольких проектах

Когда SONENTA_PROJECTS перечисляет более одного UUID, агент не может угадать, о каком проекте вы говорите, каждый вызов инструмента должен включать project_uuid. С единственным UUID (или только при заданном legacy SONENTA_PROJECT) он необязателен, и вызов по умолчанию направляется на этот проект.

аргументы tools/call

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}

Формулируйте свой запрос с учётом проекта («в проекте Checkout перечисли отсутствующие ключи для ja»), агент разрешит проект в его UUID и передаст project_uuid при вызове инструмента. Для запроса, неоднозначного между несколькими проектами, агент сначала вызовет list_projects.

Cursor (и другие MCP-клиенты)

Тот же JSON, другой файл. В Cursor положи его в .cursor/mcp.json (на проект) или ~/.cursor/mcp.json (на пользователя). Для других клиентов следуй их документации по MCP-конфигу, запись mcpServers.sonenta идентична.

.cursor/mcp.json

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}

5 инструментов V1

После настройки агент получает доступ к этим инструментам. По именам ты их не вызываешь, опиши намерение в чате, и агент сам выберет. Имена ниже, канонические идентификаторы, полезны при чтении трасс агента или при построении кастомных агентов поверх того же сервера.

list_projects Перечисляет проекты, доступные текущему API-ключу. Удобно для выбора workspace в начале чата.

Аргументы

limit number опциональный лимит на число возвращаемых проектов

Пример промпта

«List my Sonenta projects.»

get_project_info Получает метаданные проекта: исходный язык, целевые языки, namespace'ы, общее число ключей.

Аргументы

project_uuid string required

Пример промпта

«Какие языки и namespace'ы у проекта Checkout?»

list_missing_keys Возвращает накопленные события missing-keys, собранные runtime SDK (cursor-пагинация). Фильтруется по namespace или языку.

Аргументы

project_uuid string required
namespace string сузить до одного namespace (например, "checkout")
language_code string сузить до одного языка (например, "ja")
cursor string cursor пагинации, возвращённый предыдущим вызовом
limit number размер страницы (по умолчанию 20)

Пример промпта

«Какие ключи переводов отсутствуют для ja в namespace checkout?»

propose_translation Отправляет вариант перевода ключа на целевой язык. Всегда пишется как draft; повышает до approved человек-ревьюер, Sonenta это менеджер, а не движок.

Аргументы

project_uuid string required
key string required
namespace string required
language_code string required
value string required

Пример промпта

«Propose \"Confirmer la commande\" for checkout.review.confirm in fr-CA.»

validate_translations Линтит JSON i18next payload перед push'ем: парность ICU-плейсхолдеров, отсутствующие/лишние ключи, расхождение типов между локалями.

Аргументы

project_uuid string required
language_code string required
payload object required карта переводов в формате JSON i18next

Пример промпта

«Validate this translation file against the project's English source.»

Лимиты и квоты по плану

Вы платите, когда агент изменяет ваш проект, а не когда наблюдает за ним. Чтения и списки бесплатны; записи расходуют одну единицу; bulk и операции с участием ИИ масштабируются вместе с выполняемой работой.

Что считается тарифицируемым вызовом

Чтения, бесплатно

list_missing, list_keys, get_translation, search, плюс auth / discover / meta. Просматривайте очередь отсутствующих ключей хоть весь день, это никогда не затрагивает вашу квоту.

Записи, 1 единица

Каждый set / create / update / delete ключа или перевода стоит одну единицу, независимо от размера payload.

Bulk, 1 единица за ключ

Многоключевые эндпоинты (например, acknowledge) тарифицируются за каждый затронутый ключ: acknowledge на 50 ключей списывает 50 единиц, с откатом при частичном reject.

ИИ / auto-translate, ×5

Вызовы, которые задействуют LLM (auto-translate, AI Quality Review, suggest), тарифицируются по 5 единиц за вызов. Более высокий вес отражает стоимость модели.

Потолки по плану

Месячная квота, жёсткий потолок в минуту, число одновременных сессий MCP и разрешены ли записи. Те же значения питают заголовок X-MCP-Quota-Remaining в каждом ответе.

План	Единиц / месяц	Частота	Сессии	Записи
Free	NaN	NaNreq/min	NaN	заблокированы
Hobby	NaN	NaNreq/min	NaN	заблокированы
Pro	NaN	NaNreq/min	NaN	заблокированы
Team	NaN	NaNreq/min	NaN	заблокированы

Когда вы достигаете потолка

Свыше частоты в минуту → 429 mcp_rate_limited с Retry-After (секунды). Свыше месячной квоты → 429 mcp_quota_exceeded с Retry-After, установленным на момент сброса. Записи на плане Free → 403 mcp_writes_disabled. Квоты сбрасываются 1-го числа каждого календарного месяца, UTC.

Как проверить

1 Полностью перезапусти Claude Desktop (выйди и запусти снова, конфиг читается при старте).
2 Открой новый чат. Иконка молотка должна показывать sonenta с пятью доступными инструментами.
3 Напиши «List my Sonenta projects.» Агент должен вызвать list_projects и вернуть твои workspace'ы.

Застрял? Смотри логи Claude Desktop в ~/Library/Logs/Claude/mcp*.log (macOS). 90% проблем, опечатки в JSON или просроченный токен.

Обратная совместимость

Старые имена SONENTA_TOKEN и SONENTA_API_BASE (до 0.4.0) по-прежнему принимаются как фолбэк; SDK читает их молча, если канонические не заданы.

Дальше

Быстрый старт

React + i18next

Сквозной захват пропущенных ключей в рантайме.

Справка

Вся документация

CLI, API reference (в работе).