MCP

Claude Desktop einrichten

Sonenta liefert einen nativen MCP-Server, damit jeder MCP-fähige Client — Claude Desktop, Cursor, dein eigener Agent — Keys suchen, Übersetzungen vorschlagen, PRs reviewen und die Missing-Key-Queue inspizieren kann. Zwei Zeilen Config, dein Token, fertig.

1. API-Key holen

Geh in deinem Dashboard zu Org Settings → API Keys → Create. Vergib den Scope mcp:* (deckt alle fünf Tools unten ab). Das Secret wird nur einmal angezeigt; kopiere den vollständigen vrb_live_<prefix>.<secret>-String.

Speichere ihn im OS-Keychain oder in einer lokalen .env — niemals committen. Der Key ist an deine Org gebunden (und optional an ein Projekt); Calls außerhalb des Scopes liefern 404. Aus dem Dashboard jederzeit widerrufbar; widerrufene Keys liefern beim nächsten Call 401.

2. Installieren (oder überspringen)

Der MCP-Server ist auf npm und Homebrew veröffentlicht. Mit npx musst du nichts installieren — Claude Desktop zieht bei jedem Start die neueste Version. Mit brew bekommst du ein gepinntes lokales Binary, nützlich hinter strikten Firewalls.

npx (empfohlen)

1// keine Installation nötig — npx zieht das neueste @sonenta/mcp on demand2npx -y @sonenta/mcp --version

Homebrew (Alternative) Tap erscheint zu V1

1// optional: einmal global installieren — kommt mit dem V1-Launch2brew install sonenta/tap/sonenta-mcp

3. Claude Desktop verdrahten

Öffne die Config-Datei von Claude Desktop, füge den verbumia-Eintrag unter mcpServers hinzu, beende die App und starte sie neu.

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}

Drei Env-Variablen insgesamt: SONENTA_TOKEN (erforderlich), SONENTA_PROJECT (optional — pre-scope ein Projekt, damit der Agent nicht zuerst list_projects aufrufen muss) und SONENTA_API_BASE (optional — Default https://api.sonenta.com; überschreibe für Self-Hosted oder 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.

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 (und andere MCP-Clients)

Gleiches JSON, andere Datei. In Cursor leg sie unter .cursor/mcp.json ab (projektweit) oder ~/.cursor/mcp.json (userweit). Für andere Clients folge der MCP-Config-Doku deines Clients — der mcpServers.verbumia-Eintrag bleibt gleich.

.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}

Die 5 V1-Tools

Nach der Konfiguration stehen dem Agent diese Tools zur Verfügung. Du rufst sie nicht namentlich auf — beschreib deine Absicht im Chat, der Agent wählt aus. Die Namen unten sind die kanonischen Identifier, nützlich beim Lesen von Agent-Traces oder beim Bauen eigener Agents auf demselben Server.

list_projects Listet die Projekte auf, auf die der aktuelle API-Key zugreifen kann. Nützlich, um zu Beginn eines Chats einen Workspace zu wählen.

Args

limit number optionales Limit für die Anzahl zurückgegebener Projekte

Beispiel-Prompt

„List my Sonenta projects."

get_project_info Holt Projekt-Metadaten: Quellsprache, Zielsprachen, Namespaces, Gesamtanzahl Keys.

Args

project_uuid string required

Beispiel-Prompt

„Welche Sprachen und Namespaces shipt das Checkout-Projekt?"

list_missing_keys Listet ausstehende Missing-Key-Events auf, die vom Runtime-SDK erfasst wurden (cursor-paginiert). Filterbar nach Namespace oder Sprache.

Args

project_uuid string required
namespace string auf einen Namespace eingrenzen (z. B. "checkout")
language_code string auf eine Sprache eingrenzen (z. B. "ja")
cursor string Pagination-Cursor aus einem vorherigen Call
limit number Page-Size (Default 20)

Beispiel-Prompt

„Welche Übersetzungs-Keys fehlen für ja im Checkout-Namespace?"

propose_translation Reicht einen Übersetzungswert für einen Key in einer Zielsprache ein. Wird immer als Draft geschrieben; ein menschlicher Reviewer promotet später — Sonenta ist der Manager, nicht die Engine.

Args

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

Beispiel-Prompt

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

validate_translations Lintet eine JSON-i18next-Payload vor dem Push: ICU-Placeholder-Parität, fehlende/zusätzliche Keys, Type-Drift zwischen Locales.

Args

project_uuid string required
language_code string required
payload object required Übersetzungs-Map im JSON-i18next-Format

Beispiel-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.

Funktion prüfen

1 Starte Claude Desktop komplett neu (beenden, neu starten — die Config wird beim Start gelesen).
2 Öffne einen neuen Chat. Das Hammer-Icon sollte verbumia mit 5 verfügbaren Tools zeigen.
3 Tippe „List my Sonenta projects." Der Agent sollte list_projects aufrufen und deine Workspaces zurückgeben.

Hängst fest? Schau in die Logs von Claude Desktop unter ~/Library/Logs/Claude/mcp*.log (macOS). 90 % der Probleme sind Tippfehler im JSON oder ein veralteter Token.

Backwards compatibility

Die älteren Namen SONENTA_TOKEN und SONENTA_API_BASE (pre-0.4.0) werden weiterhin als Fallback akzeptiert; das SDK liest sie still, wenn die kanonischen Namen nicht gesetzt sind.

Weiter

Schnellstart

React + i18next

Fehlende Keys zur Laufzeit erfassen, end-to-end.

Referenz

Alle Docs

CLI, API-Referenz (in Arbeit).