Docs / Guides
Drive Studio with a browser agent
Register Verbatra Studio's review actions as WebMCP tools so a browser AI agent can work your open, authenticated dashboard tab.
Use this to let a browser AI agent, such as Gemini or Claude in Chrome, check drift, work the review queue and fix entries in the Studio tab you have open. It is not for project setup or remote access.
You need:
- Studio running over your project (Review in Studio);
- Chrome 149 or later with
chrome://flags/#enable-webmcp-testingenabled, or a browser with native WebMCP support, in a normal window rather than a headless one.
Experimental
WebMCP is a new browser capability behind a flag, and its surface may still change.
Turn the tools on
verbatra studio --expose-agent-toolsVERBATRA_ does the same; Spend and agent tools shows how the flag and the variable resolve. Open the printed URL in the WebMCP browser, and the agent on that tab finds the tools. In a browser without WebMCP, Studio registers nothing.
To let the agent call your provider, start Studio with --allow-spend as well.
The agent reads every value unredacted, as the page shows it, because an agent on the tab can read the page anyway. The exceptions are the glossary tools and verbatra_: their values pass through secret redaction, so a value shaped like an API key comes back as a placeholder. To keep values from an agent, use the MCP server with --redact-values instead; for an NDA project, see Studio and MCP.
Know what the agent can call
Each tool is a Studio action with a verbatra_ prefix. Read tools are marked read-only, write tools change only your local files, and spend tools register only with --allow-spend.
Read tools
| Tool | What it does |
|---|---|
verbatra_ | the loaded config, the capabilities, and, under capabilities.limits, the rate limits of retranslate, reviewDecision and the two value-replace methods |
verbatra_ | coverage per locale |
verbatra_ | missing, changed and orphaned keys per locale |
verbatra_ | the resolved glossary, secret-redacted |
verbatra_ | the lock file's state per locale |
verbatra_ | recent commits to the locale files, with the author's name (never the email) |
verbatra_ | one key's commits in one locale, with word diffs, keys scrubbed new |
verbatra_ | placeholder, markup and ICU checks for one key, in the locales where its source changed |
verbatra_ | every machine-written value nobody has approved, from the committed files |
verbatra_ | one key's source and target, with who wrote the target |
verbatra_ | one key's description, glossary terms and maxLength, and a check of an optional draft |
verbatra_ | key values per target locale, 200 per page by default, narrowed by locales, keys or query |
verbatra_ | every translation that fails the integrity checks |
verbatra_ | what a translate-pending call would send and cost, without calling a provider |
verbatra_ | the last run's token usage and budget |
verbatra_ | recorded runs, newest first, with tokens, cost and coverage, as counts only new |
Write tools
| Tool | What it does |
|---|---|
verbatra_ | change one term of a file-backed glossary |
verbatra_ | record a named person's approval of one value |
verbatra_ | record a named person's rejection, removing the value |
verbatra_ | write one value through the integrity gate |
Spend tools
| Tool | What it does |
|---|---|
verbatra_ | retranslate one key in one locale |
verbatra_ | translate everything pending, optionally for some locales under a maxTokens ceiling |
verbatra_ returns only the locales where the key's source changed, so an empty list means nothing needed checking. Its rows are flatter than the MCP server's key.integrity. Only the MCP server has project.doctor and report.provenance. verbatra_ pages like its locale.values, with the same limit and cursor (More inputs and results).
Know the rules the tools follow
Every call goes through the dashboard's own authenticated loopback RPC, with the same input validation and integrity gate: a value that fails a check is rejected, not written.
Per-call rules
- Provenance: an agent's edit is recorded with the origin
agentand stays in the review queue; a dashboard edit ishuman. The read tools report who wrote each value (The lock file). - Human work: retranslating refuses a person's value with
KEY_(except withPROTECTED humanEdits: "overwrite") and a pinned key withKEY_, and editing refuses a pinned key (Keep human translations).PINNED - Review decisions: approve and reject only relay your decision. Both need
reviewer, the person's name, andexpectedValue, the text reviewed; a changed value is refused withREVIEW_.VALUE_ CHANGED - No bulk tools: Approve selected, Reject selected, Retranslate selected, Approve all in and Search and replace stay person-only.
- Estimate first: an unknown locale is refused with
UNKNOWN_before anything is spent, and the lower of the call's and the config'sLOCALE maxTokensapplies (Estimate cost before a run). - Rate limits: per rolling minute, 20 retranslations, 20 edits, 20 glossary writes, 60 review decisions and 5 translate-pending calls, one at a time.
Read a failed call
Every tool returns the dashboard's envelope, so a failure reads { "ok": false, "error": { "code": ..., "message": ... } }. Besides the SDK's own codes, the RPC layer adds:
| Code | Meaning |
|---|---|
REQUEST_ | the request or the answer was not a readable envelope |
METHOD_ | the method does not exist on this Studio version |
SPEND_ | a spend method while spending is off: Studio runs without --allow-spend, or the provider is none; the message names which |
PARAMS_ | a parameter failed validation; issues names each field |
METHOD_ | over the rate limit; retryAfterSeconds says when the call fits |
BATCH_ | a batch exceeds a whole rate-limit window; send fewer entries |
ALREADY_ | a second call for an entry still in flight (HTTP 409) |
SESSION_ | Studio restarted with a new token; open the URL it printed |
INTERNAL | a handler failed with an unexpected error (HTTP 500); the message is generic |
Fix degraded tools
If the browser rejects a registration, every view shows a warning such as:
Agent tools degraded: 2 of the agent tool registrations failed with SecurityError. The dashboard itself is unaffected. The browser console lists every failing tool.
The console has one line naming each failure:
Verbatra agent tools: 2 of 20 tool registrations failed. verbatra_status_diff (SecurityError: ...); verbatra_key_value (SecurityError: ...)Read the error name there first, then reload the tab, which runs registration again. A missing flag or a browser without WebMCP never shows this notice; it registers nothing, silently. A session without --allow-spend attempts two fewer registrations, which is not a failure.
Weigh the spend risk
The tools add no network exposure: Studio still binds only to 127.0.0.1, every request carries the session token, and tools that return project text mark it as untrusted, so the agent treats it as data.
Warning
With both --allow-spend and --expose-agent-tools, an agent can spend on your provider without a per-call confirmation, up to the rate limits. Studio cannot tell an agent's call from your click, so it adds no approval dialog. For read-and-edit only, leave --allow-spend off.
Related
- Review in Studio: the same workflow by hand.
verbatra studio: every flag and the startup contract.- Connect an MCP client: the plugin carries the
verbatra-studio-agent-toolsskill, but you start Studio yourself.