MCP

API reference

Verbumia 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 vrb_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 @verbumia/mcp on demand2npx -y @verbumia/mcp --version

Homebrew (alternative) Tap publishes at V1

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

3. Wire Claude Desktop

Open Claude Desktop's config file, add the verbumia 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    "verbumia": {6      "command": "npx",7      "args": ["-y", "@verbumia/mcp"],8      "env": {9        "VERBUMIA_TOKEN":   "vrb_live_<prefix>.<secret>",10        "VERBUMIA_PROJECT": "<project_uuid>"11      }12    }13  }14}

Three env vars total: VERBUMIA_TOKEN (required), VERBUMIA_PROJECT (optional — pre-scope a project so the agent doesn't need to call list_projects first), and VERBUMIA_API_BASE (optional — defaults to https://api.verbumia.ca; override for self-hosted or staging).

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.verbumia entry is identical.

.cursor/mcp.json

1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "verbumia": {5      "command": "npx",6      "args": ["-y", "@verbumia/mcp"],7      "env": { "VERBUMIA_TOKEN": "vrb_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 Verbumia 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 — Verbumia 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."

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 verbumia with 5 tools available.
3 Type "List my Verbumia projects." The agent should call list_projects and return your workspaces.