MCP

Claude Desktop をセットアップ

Verbumia はネイティブの MCP サーバーを提供しているので、MCP に対応した任意のクライアント — Claude Desktop、Cursor、自作のエージェント — からキー検索、翻訳の提案、PR レビュー、欠落キューの参照ができます。設定 2 行とトークンで完了です。

1. API キーを取得

ダッシュボードで Org Settings → API Keys → Create に進みます。スコープは mcp:*(以下の 5 つのツールすべてをカバー)。シークレットは 1 度だけ 表示されるので、vrb_live_<prefix>.<secret> 文字列の全体をコピーしてください。

OS のキーチェーン、またはローカルの .env に保存し、絶対にコミットしないでください。キーは org に紐づき(任意で 1 プロジェクトにも)、スコープ外の呼び出しは 404 を返します。ダッシュボードからいつでも失効可能で、失効後は次回呼び出しで 401 になります。

2. インストール(または省略)

MCP サーバーは npm と Homebrew で公開されています。npx を使えばインストール不要 — Claude Desktop が起動ごとに最新版を取得します。brew なら固定したローカルバイナリが手に入り、厳しいファイアウォール環境で便利です。

npx(推奨)

1// インストール不要 — npx が必要に応じて最新の @verbumia/mcp を取得します2npx -y @verbumia/mcp --version

Homebrew(代替) Tap は V1 公開予定

1// 任意: グローバルに 1 度インストール — V1 ローンチに合わせて提供2brew install verbumia/tap/verbumia-mcp

3. Claude Desktop に接続

Claude Desktop の設定ファイルを開き、mcpServers の下に verbumia エントリを追加してから、アプリを終了して再起動します。

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}

環境変数は計 3 つです: VERBUMIA_TOKEN(必須)、VERBUMIA_PROJECT(任意 — プロジェクトを事前指定すると、エージェントが先に list_projects を呼ぶ必要がなくなります)、VERBUMIA_API_BASE(任意 — デフォルトは https://api.verbumia.dev。セルフホストやステージング向けに上書きしてください)。

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(およびその他の MCP クライアント)

JSON は同じで、ファイルの場所が違います。Cursor では .cursor/mcp.json(プロジェクト単位)または ~/.cursor/mcp.json(ユーザー単位)に置きます。他のクライアントでは、それぞれの MCP 設定ドキュメントに従ってください — mcpServers.verbumia エントリは同一です。

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

V1 の 5 つのツール

設定後、エージェントはこれらのツールを利用できます。名前で直接呼び出すのではなく、チャットで意図を伝えればエージェントが選択します。以下の名前はキャノニカル ID で、エージェントトレースを読むときや、同じサーバー上にカスタムエージェントを構築するときに役立ちます。

list_projects 現在の API キーでアクセスできるプロジェクトを列挙します。チャット冒頭でワークスペースを選ぶのに便利です。

引数

limit number 返されるプロジェクト数の任意上限

プロンプト例

「List my Verbumia projects.」

get_project_info プロジェクトのメタデータを取得します: ソース言語、ターゲット言語、namespace、キーの総数。

引数

project_uuid string required

プロンプト例

「Checkout プロジェクトはどの言語と namespace を扱っていますか?」

list_missing_keys ランタイム SDK が捕捉した欠落キーイベント(cursor ページネーション)を一覧します。namespace または言語でフィルタ可能です。

引数

project_uuid string required
namespace string 1 つの namespace に絞り込み(例: "checkout")
language_code string 1 つの言語に絞り込み(例: "ja")
cursor string 前回呼び出しで返ったページネーション cursor
limit number ページサイズ(デフォルト 20)

プロンプト例

「checkout namespace で ja に欠けている翻訳キーは?」

propose_translation ターゲット言語のキーに翻訳値を提案します。常に draft として保存され、人間のレビュアーが後でプロモートします — Verbumia はマネージャーであり、エンジンではありません。

引数

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

プロンプト例

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

validate_translations push 前に JSON i18next ペイロードをリント: ICU プレースホルダーの整合性、欠落/余剰キー、ロケール間の型ドリフト。

引数

project_uuid string required
language_code string required
payload object required JSON i18next 形式の翻訳マップ

プロンプト例

「この翻訳ファイルをプロジェクトの英語ソースと照合して検証して。」

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.

動作確認

1 Claude Desktop を完全に再起動します(終了 → 再起動。設定は起動時に読み込まれます)。
2 新しいチャットを開きます。ハンマーアイコンに verbumia と 5 つのツールが表示されるはずです。
3 「List my Verbumia projects.」 と入力してください。エージェントが list_projects を呼び、ワークスペース一覧を返します。