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)

# no install needed - npx pulls the latest @sonenta/mcp on demand
npx -y @sonenta/mcp --version

Homebrew (alternative)

# optional: install once globally
brew 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.

%APPDATA%/Claude/claude_desktop_config.json

// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "sonenta": {
      "command": "npx",
      "args": ["-y", "@sonenta/mcp"],
      "env": {
        "SONENTA_API_KEY": "snt_live_<prefix>.<secret>",
        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"
      }
    }
  }
}

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

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.

// list_missing_keys - project_uuid is REQUIRED when SONENTA_PROJECTS lists more than one UUID
{
  "name": "list_missing_keys",
  "arguments": {
    "project_uuid": "<uuid1>",
    "namespace": "checkout",
    "language_code": "ja"
  }
}

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 (project-scoped) or ~/.cursor/mcp.json (user-scoped)
{
  "mcpServers": {
    "sonenta": {
      "command": "npx",
      "args": ["-y", "@sonenta/mcp"],
      "env": { "SONENTA_API_KEY": "snt_live_<prefix>.<secret>" }
    }
  }
}

The 5 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	500	10 req/min	1	blocked
Hobby	5 000	30 req/min	2	allowed
Pro	50 000	120 req/min	10	allowed
Team	250 000	600 req/min	50	allowed

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.

Next

• Quickstart: React + i18next: Capture missing keys at runtime, end-to-end. /docs-next/en/getting-started/installation/
• Reference: All docs: CLI, API reference (in progress). /docs-next/en/

Tool reference

The full list of MCP tools, with their arguments: see the MCP reference.