Operate Studio with a browser agent

Expose Verbatra Studio's review actions as WebMCP tools so a browser AI agent can drive the same operations from your open, authenticated dashboard tab.

Page traduite automatiquement

Cette page a été traduite automatiquement, elle peut donc contenir des erreurs ou sonner un peu bizarrement. La version anglaise est la référence. Lire l'original en anglais.

Verbatra Studio is normally a human surface: you open the loopback dashboard and click through project state, drift, the needs-review queue, and edits. With the opt-in --expose-agent-tools flag, Studio also registers those same review actions as WebMCP tools, so a browser AI agent (for example Gemini or Claude running inside Chrome) sitting on the same open, authenticated tab can operate them in a structured way instead of guessing at the DOM.

This is for operating an existing verbatra project conversationally: inspecting state and drift, working the needs-review queue, editing entries, and (only when you also allow spend) retranslating and translating pending keys. It is not for project setup and not for remote access.

Experimental and browser-flag-gated

WebMCP is a new, evolving browser capability. Today it requires a specific Chrome build with an experimental flag, and the surface may change as the standard matures. Treat this as a preview feature.

What WebMCP is

WebMCP lets a page register tools on document.modelContext that a browser-resident AI agent can then call. Studio uses this to advertise its review actions as named tools. Every tool call still travels through the exact same authenticated RPC as the dashboard, over the same loopback origin, with the same input validation and the same capability gates. Registering the tools grants an agent nothing the open, authenticated tab did not already have: an agent driving the DOM could already reach every one of these actions. The surface is co-extensive with that one open tab and adds no new network exposure.

Browser requirements

A WebMCP-capable browser. Today that means Chrome 149 or later with chrome://flags/#enable-webmcp-testing enabled, or a later browser with native support.
document.modelContext must be present. When it is absent, Studio registers nothing and the dashboard is unchanged.
A real browsing context. This does not work headless; the agent operates the live, open tab.
No configuration or CSP change on Studio's side. The WebMCP tools Permissions-Policy defaults to self, which is exactly Studio's same-origin case, so nothing needs to be granted.

Enable it

Agent tools are off by default. Turn them on with the flag on the studio command:

verbatra studio --expose-agent-tools

Or set the environment fallback:

VERBATRA_STUDIO_AGENT_TOOLS=1 verbatra studio

The flag and the environment variable resolve exactly like --allow-spend: 1, true, yes, or on (case-insensitive) counts as on, and the CLI flag wins over the variable. With neither set, no tools are registered. See verbatra studio for every flag.

Then open the printed loopback URL in your WebMCP-capable browser. The agent on that tab discovers the registered tools and can call them.

The tool catalog

With the opt-in on, Studio registers thirteen tools, one per dashboard action. Without --allow-spend it registers eleven: the two spend tools are omitted entirely. Tool names are prefixed and use underscores (for example verbatra_project_snapshot).

Read tools (ten)

Inspect project state without changing anything. These are marked read-only.

Tool	What it returns
`verbatra_project_snapshot`	resolved project state and capabilities
`verbatra_status_check`	per-locale coverage summary
`verbatra_status_diff`	per-locale drift (missing, changed, orphaned keys)
`verbatra_glossary_get`	the resolved glossary
`verbatra_lock_state`	the lock file's state
`verbatra_history_list`	recent locale file commit history
`verbatra_key_integrity`	placeholder and ICU integrity for a key
`verbatra_review_queue`	the needs-review queue
`verbatra_usage_summary`	the last run's token usage and budget
`verbatra_key_value`	the source and target values for one key and locale

Write tool (one)

verbatra_translation_editEntry edits one locale's value in place. It goes through the same integrity gate as every other verbatra write: a value that drops or invents a placeholder, or breaks an ICU message's structure, is rejected and nothing is written. An accepted edit writes the locale file and advances the key's lock entry, exactly as a dashboard edit does. Editing needs no spend flag; it touches only your local files and never calls a provider.

Spend tools (two)

These call a translation provider and are registered only when Studio also runs with --allow-spend:

verbatra_translation_retranslateEntry: retranslate one key and locale.
verbatra_translation_translatePending: translate everything currently pending.

Both run their results through the integrity gate before anything reaches disk, and both are subject to Studio's existing rate limits (retranslate at 20 per rolling minute, translate-pending at 5 per rolling minute plus a single-concurrent guard). Without --allow-spend, they are absent from the tool set and the server does not register the underlying endpoints at all, so spend you did not grant at startup cannot be reached from an agent.

Security model

Keep these points in mind before you enable agent tools.

Off by default. You opt in explicitly with --expose-agent-tools (or VERBATRA_STUDIO_AGENT_TOOLS).
Spend requires both flags. The two spend tools appear only when you pass both --expose-agent-tools and --allow-spend. Neither flag implies the other. Read and write tools do not spend.
No new network exposure. Every tool call uses the same authenticated loopback RPC as the dashboard. Studio still binds only to 127.0.0.1, and the browser session token still authenticates every request.
Translatable strings are untrusted. Tools that can return project-derived text (locale strings, key names, glossary terms, commit subjects, placeholder tokens) mark their content as untrusted, so a consuming agent treats those values as data, not as instructions.

The accepted spend risk

State this one plainly. With both --allow-spend and --expose-agent-tools on, an autonomous agent can trigger provider spend without a per-click human confirmation. Studio does not add a per-call approval dialog: the server cannot tell an agent-originated call apart from a human click on the same session, so such a dialog would give false assurance and would defeat the point of the feature. The rate limits above still bound the cost, but an agent can loop up to that ceiling on its own.

Enable agent-driven spend deliberately. If you only want an agent to inspect state and fix entries by hand, run Studio without --allow-spend: agent tools work fully in that read-and-edit mode, and no tool can reach a provider.

Review translations in Studio: the same workflow, driven by a human.
verbatra studio: every flag and the startup contract.
Translation safety: the integrity gate that every edit and retranslate passes through.

Edit on GitHub