MCP

Set up Claude Desktop

Sonenta ships a native MCP server so any MCP-aware client — Claude Desktop, Cursor, your own agent — can search keys, propose translations, review PRs, and inspect the missing-key queue. Two lines of config, your token, done.

1. Get an API key

In your dashboard, go to Org Settings → API Keys → Create. Give it the mcp:* scope (covers all five tools below). The secret is shown once; copy the full snt_live_<prefix>.<secret> string.

Store it in your OS keychain or a local .env — never commit it. The key is bound to your org (and optionally one project); calls outside that scope return 404. Revoke from the dashboard at any time; revoked keys 401 on the next call.

2. Install (or skip)

The MCP server is published to npm and Homebrew. With npx you don't need to install anything — Claude Desktop pulls the latest version on every launch. With brew you get a pinned local binary, useful behind strict firewalls.

npx (recommended)

1// no install needed — npx pulls the latest @sonenta/mcp on demand2npx -y @sonenta/mcp --version

Homebrew (alternative) Tap publishes at V1

1// optional: install once globally — coming with the V1 launch2brew install sonenta/tap/sonenta-mcp

3. Wire Claude Desktop

Open Claude Desktop's config file, add the sonenta entry under mcpServers, then quit and relaunch the app.

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}

Three env vars total: SONENTA_API_KEY (required, the API key from your dashboard), SONENTA_PROJECTS (optional, CSV of project UUIDs — with a single UUID the agent skips list_projects; with several UUIDs, every tool call must pass project_uuid to disambiguate), and SONENTA_BASE_URL (optional — defaults to https://api.sonenta.com; override for self-hosted or 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 (and other MCP clients)

Same JSON, different file. In Cursor, drop it at .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped). For other clients, follow your client's MCP-config docs — the mcpServers.sonenta entry is identical.

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

The 5 V1 tools

Once configured, the agent has these tools available. You don't call them by name — describe your intent in chat and the agent picks. Names below are the canonical identifiers, useful when reading agent traces or building custom agents on top of the same server.

list_projects Enumerate the projects the current API key can access. Useful for picking a workspace at the start of a chat.

Args

limit number optional cap on the number of projects returned

Sample prompt

"List my Sonenta projects."

get_project_info Fetch project metadata: source language, target languages, namespaces, total key count.

Args

project_uuid string required

Sample prompt

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

list_missing_keys List pending missing-key events captured by the runtime SDK (cursor-paginated). Filter by namespace or language.

Args

project_uuid string required
namespace string narrow to one namespace (e.g. "checkout")
language_code string narrow to one language (e.g. "ja")
cursor string pagination cursor returned by a prior call
limit number page size (default 20)

Sample prompt

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

propose_translation Submit a translation value for a key in a target language. Always written as draft; a human reviewer promotes it later — Sonenta is the manager, not the engine.

Args

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

Sample prompt

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

validate_translations Lint a JSON i18next payload before pushing: ICU placeholder parity, missing/extra keys, type drift across locales.

Args

project_uuid string required
language_code string required
payload object required JSON i18next-shaped translation map

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

Verifying it works

1 Restart Claude Desktop fully (quit, relaunch — the config is read at startup).
2 Open a new chat. The hammer icon should show sonenta with 5 tools available.
3 Type "List my Sonenta projects." The agent should call list_projects and return your workspaces.

Stuck? Check Claude Desktop's logs at ~/Library/Logs/Claude/mcp*.log (macOS). 90% of issues are typos in the JSON or a stale token.

Backwards compatibility

The singular SONENTA_PROJECT is still accepted as a fallback when SONENTA_PROJECTS is unset (since 0.11.0). If both are set, SONENTA_PROJECTS wins and the SDK prints to stderr: sonenta-mcp: both SONENTA_PROJECTS and SONENTA_PROJECT are set; SONENTA_PROJECTS wins. Remove SONENTA_PROJECT to silence this warning. The pre-0.4.0 names SONENTA_TOKEN and SONENTA_API_BASE are also still accepted as silent fallbacks.

Quickstart

React + i18next

Capture missing keys at runtime, end-to-end.

Reference

All docs

CLI, API reference (in progress).