MCP

Configurar o Claude Desktop

O Verbumia inclui um servidor MCP nativo para que qualquer cliente compatível com MCP — Claude Desktop, Cursor, o teu próprio agente — possa procurar chaves, propor traduções, rever PRs e inspecionar a fila de chaves em falta. Duas linhas de config, o teu token, pronto.

1. Obtém uma API key

No teu dashboard, vai a Org Settings → API Keys → Create. Atribui-lhe o scope mcp:* (cobre as cinco ferramentas abaixo). O secret é mostrado uma única vez; copia a string completa vrb_live_<prefix>.<secret>.

Guarda-a no keychain do teu SO ou num .env local — nunca a faças commit. A key está ligada à tua org (e opcionalmente a um projeto); chamadas fora desse scope devolvem 404. Revoga a partir do dashboard quando quiseres; keys revogadas devolvem 401 na chamada seguinte.

2. Instala (ou salta)

O servidor MCP é publicado no npm e no Homebrew. Com npx não precisas de instalar nada — o Claude Desktop puxa a versão mais recente a cada arranque. Com brew obténs um binário local fixo, útil atrás de firewalls restritivos.

npx (recomendado)

1// sem instalação — npx puxa o último @verbumia/mcp a pedido2npx -y @verbumia/mcp --version

Homebrew (alternativa) Tap publica no V1

1// opcional: instala globalmente uma vez — chega com o lançamento V12brew install verbumia/tap/verbumia-mcp

3. Liga o Claude Desktop

Abre o ficheiro de config do Claude Desktop, adiciona a entrada verbumia sob mcpServers, depois fecha e relança a 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@^0.11.0"],8      "env": {9        "VERBUMIA_API_KEY": "vrb_live_<prefix>.<secret>",10        "VERBUMIA_PROJECTS": "<uuid1>,<uuid2>"11      }12    }13  }14}

Três variáveis de ambiente no total: VERBUMIA_TOKEN (obrigatória), VERBUMIA_PROJECT (opcional — pré-define um projeto para que o agente não tenha de chamar list_projects primeiro) e VERBUMIA_API_BASE (opcional — por defeito https://api.verbumia.dev; sobrescreve para self-hosted ou staging).

VERBUMIA_PROJECTS requires @verbumia/mcp ≥ 0.11.0. On older releases, see Backwards compatibility below.

Multi-project tool calls

When VERBUMIA_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 VERBUMIA_PROJECT set), it's optional and defaults to that project.

tools/call arguments

1// list_missing_keys — project_uuid is REQUIRED when VERBUMIA_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 (e outros clientes MCP)

Mesmo JSON, ficheiro diferente. No Cursor, coloca-o em .cursor/mcp.json (scope de projeto) ou ~/.cursor/mcp.json (scope de utilizador). Para outros clientes, segue a doc de configuração MCP do teu cliente — a entrada mcpServers.verbumia é idêntica.

.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@^0.11.0"],7      "env": { "VERBUMIA_API_KEY": "vrb_live_<prefix>.<secret>" }8    }9  }10}

As 5 ferramentas V1

Uma vez configurado, o agente tem estas ferramentas disponíveis. Não as chamas por nome — descreve a tua intenção no chat e o agente escolhe. Os nomes abaixo são os identificadores canónicos, úteis ao ler traces do agente ou ao construir agentes próprios sobre o mesmo servidor.

list_projects Enumera os projetos a que a API key atual tem acesso. Útil para escolher um workspace no início de um chat.

Args

limit number limite opcional ao número de projetos devolvidos

Prompt de exemplo

"Lista os meus projetos Verbumia."

get_project_info Vai buscar os metadados do projeto: língua de origem, línguas de destino, namespaces, total de chaves.

Args

project_uuid string required

Prompt de exemplo

"Que línguas e namespaces tem o projeto Checkout?"

list_missing_keys Lista os eventos pendentes de chaves em falta capturados pelo SDK em runtime (paginado por cursor). Filtra por namespace ou língua.

Args

project_uuid string required
namespace string restringe a um namespace (p. ex. "checkout")
language_code string restringe a uma língua (p. ex. "ja")
cursor string cursor de paginação devolvido por uma chamada anterior
limit number tamanho da página (default 20)

Prompt de exemplo

"Que chaves de tradução faltam para ja no namespace checkout?"

propose_translation Submete um valor de tradução para uma chave numa língua de destino. Sempre escrito como draft; um revisor humano promove-o depois — o Verbumia é o gestor, não o motor.

Args

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

Prompt de exemplo

"Propõe \"Confirmer la commande\" para checkout.review.confirm em fr-CA."

validate_translations Faz lint de um payload JSON i18next antes do push: paridade dos placeholders ICU, chaves em falta/a mais, drift de tipo entre locales.

Args

project_uuid string required
language_code string required
payload object required mapa de traduções em formato JSON i18next

Prompt de exemplo

"Valida este ficheiro de tradução contra a fonte inglesa do projeto."

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.

Verificar que funciona

1 Reinicia o Claude Desktop por completo (sai, relança — a config é lida no arranque).
2 Abre um novo chat. O ícone do martelo deve mostrar verbumia com 5 ferramentas disponíveis.
3 Escreve "List my Verbumia projects." O agente deve chamar list_projects e devolver os teus workspaces.

Empancado? Verifica os logs do Claude Desktop em ~/Library/Logs/Claude/mcp*.log (macOS). 90% dos problemas são typos no JSON ou um token caducado.

Backwards compatibility

Os nomes pré-0.4.0 VERBUMIA_TOKEN e VERBUMIA_API_BASE continuam aceites como fallback; o SDK lê-os em silêncio se os canónicos não estiverem definidos.

Seguinte

Início rápido

React + i18next

Captura chaves em falta em runtime, ponta a ponta.

Referência

Todas as docs

CLI, referência API (em curso).