MCP

Skonfiguruj Claude Desktop

Sonenta dostarcza natywny serwer MCP, dzięki czemu każdy klient świadomy MCP — Claude Desktop, Cursor, twój własny agent — może wyszukiwać klucze, proponować tłumaczenia, recenzować PR-y i przeglądać kolejkę brakujących kluczy. Dwie linijki konfiguracji, twój token, gotowe.

1. Pobierz klucz API

W panelu przejdź do Org Settings → API Keys → Create. Nadaj scope mcp:* (obejmuje wszystkie pięć narzędzi poniżej). Sekret pokazuje się tylko raz; skopiuj cały string vrb_live_<prefix>.<secret>.

Trzymaj go w keychainie systemu lub lokalnym .env — nigdy nie commituj. Klucz jest powiązany z twoją organizacją (i opcjonalnie z jednym projektem); calle poza scope zwracają 404. Unieważnij w panelu w dowolnej chwili; unieważnione klucze zwracają 401 przy kolejnym callu.

2. Instalacja (lub pomiń)

Serwer MCP publikowany jest na npm i Homebrew. Z npx nie musisz nic instalować — Claude Desktop pobiera najnowszą wersję przy każdym uruchomieniu. Z brew dostajesz przypięty lokalny binarny — przydatne za rygorystycznymi firewallami.

npx (zalecane)

1// instalacja niepotrzebna — npx pobiera najnowsze @sonenta/mcp na żądanie2npx -y @sonenta/mcp --version

Homebrew (alternatywa) Tap publikowany przy V1

1// opcjonalnie: instalacja raz globalnie — pojawi się przy starcie V12brew install sonenta/tap/sonenta-mcp

3. Podłącz Claude Desktop

Otwórz plik konfiguracyjny Claude Desktop, dodaj wpis verbumia pod mcpServers, potem zamknij i ponownie uruchom aplikację.

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": "vrb_live_<prefix>.<secret>",10        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"11      }12    }13  }14}

Trzy zmienne env w sumie: SONENTA_TOKEN (wymagana), SONENTA_PROJECT (opcjonalna — wstępnie zawęź projekt, by agent nie musiał najpierw wołać list_projects) oraz SONENTA_API_BASE (opcjonalna — domyślnie https://api.sonenta.com; nadpisz dla self-hosted lub stagingu).

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.

tools/call arguments

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 (i inni klienci MCP)

Ten sam JSON, inny plik. W Cursor wrzuć go do .cursor/mcp.json (scope projektu) albo ~/.cursor/mcp.json (scope użytkownika). Dla innych klientów postępuj zgodnie z dokumentacją konfiguracji MCP twojego klienta — wpis mcpServers.verbumia jest identyczny.

.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": "vrb_live_<prefix>.<secret>" }8    }9  }10}

5 narzędzi V1

Po konfiguracji agent ma dostęp do tych narzędzi. Nie wołasz ich po nazwie — opisz swój zamiar w czacie, a agent wybierze. Nazwy poniżej to kanoniczne identyfikatory, przydatne przy czytaniu trace'ów agenta lub budowaniu własnych agentów na tym samym serwerze.

list_projects Wylicza projekty, do których ma dostęp aktualny klucz API. Przydatne, by wybrać workspace na początku czatu.

Args

limit number opcjonalny limit liczby zwracanych projektów

Przykładowy prompt

„List my Sonenta projects."

get_project_info Pobiera metadane projektu: język źródłowy, języki docelowe, namespacy, łączną liczbę kluczy.

Args

project_uuid string required

Przykładowy prompt

„What languages and namespaces does the Checkout project ship?"

list_missing_keys Listuje oczekujące zdarzenia brakujących kluczy zarejestrowane przez SDK runtime (paginacja kursorem). Filtrowalne po namespace lub języku.

Args

project_uuid string required
namespace string zawęź do jednego namespace (np. "checkout")
language_code string zawęź do jednego języka (np. "ja")
cursor string kursor paginacji zwrócony przez wcześniejszy call
limit number rozmiar strony (domyślnie 20)

Przykładowy prompt

„What translation keys are missing for ja in the checkout namespace?"

propose_translation Wysyła wartość tłumaczenia dla klucza w języku docelowym. Zawsze zapisywane jako draft; recenzent ludzki promuje później — Sonenta jest menedżerem, nie silnikiem.

Args

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

Przykładowy prompt

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

validate_translations Lintuje payload JSON i18next przed pushem: parytet placeholderów ICU, brakujące/nadmiarowe klucze, dryf typów między locale.

Args

project_uuid string required
language_code string required
payload object required mapa tłumaczeń w kształcie JSON i18next

Przykładowy prompt

„Validate this translation file against the project's English source."

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

Reads — free

list_missing, list_keys, get_translation, search, plus auth / discover / meta. Browse the missing-key queue all day — it never touches your quota.

Writes — 1 unit

Each set / create / update / delete on a key or translation costs one unit, regardless of payload size.

Bulk — 1 unit per key

Multi-key endpoints (e.g. acknowledge) bill per key touched: a 50-key acknowledge debits 50 units, with rollback on partial-reject.

AI / auto-translate — ×5

Calls that invoke an LLM (auto-translate, AI Quality Review, suggest) bill 5 units per call. Higher weight reflects model cost.

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.

Plan	Units / month	Rate	Sessions	Writes
Free	NaN	NaNreq/min	NaN	blocked
Hobby	NaN	NaNreq/min	NaN	blocked
Pro	NaN	NaNreq/min	NaN	blocked
Team	NaN	NaNreq/min	NaN	blocked

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.

Weryfikacja

1 Zrestartuj Claude Desktop w pełni (zamknij, uruchom ponownie — konfiguracja czytana jest przy starcie).
2 Otwórz nowy czat. Ikona młotka powinna pokazać verbumia z 5 dostępnymi narzędziami.
3 Wpisz „List my Sonenta projects." Agent powinien wywołać list_projects i zwrócić twoje workspace'y.

Utknąłeś? Sprawdź logi Claude Desktop w ~/Library/Logs/Claude/mcp*.log (macOS). 90% problemów to literówki w JSON-ie albo nieaktualny token.

Backwards compatibility

Starsze nazwy SONENTA_TOKEN i SONENTA_API_BASE (sprzed 0.4.0) są nadal akceptowane jako fallback; SDK czyta je po cichu, jeśli kanoniczne nazwy nie są ustawione.

Dalej

Szybki start

React + i18next

Wyłapuj brakujące klucze w runtime, end-to-end.

Referencja

Wszystkie dokumenty

CLI, referencja API (w toku).