---
title: "verbatra mcp"
description: "Start the stdio MCP server that exposes verbatra's tools to any MCP client, with tools that call a paid provider kept off the list by default."
type: "reference"
---
# verbatra mcp

Start the stdio MCP server that exposes verbatra's tools to any MCP client, with tools that call a paid provider kept off the list by default.

Start a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, the transport clients such as Claude Code or Cursor use to launch a tool server. It serves protocol revisions 2024-10-07 to 2026-07-28. There is no HTTP transport, which would expose write and spend tools.

<AvailableFrom version="0.2.0" pkg="@verbatra/mcp" />

## Synopsis [#synopsis]

```bash
verbatra mcp [flags]
verbatra-mcp [flags]
```

- `verbatra-mcp` is the binary `@verbatra/mcp` ships, so a client can spawn the server without the CLI. It takes the same flags except `-q`/`--quiet` and starts the same server, but loads no `.env` file and prints the `@verbatra/mcp` version for `--version`.
- Both exit `2` on an unknown flag, missing flag value or stray argument. `verbatra-mcp` does so, with `-h` and `-V` from `@verbatra/mcp` 0.3.0.

## Examples [#examples]

```bash
# start the MCP server with only local, non-spending tools
verbatra mcp

# also advertise the provider-calling tools
verbatra mcp --allow-spend

# resolve a project outside the current directory
verbatra mcp --cwd /path/to/project --config verbatra.config.ts

# run the standalone server without the CLI
npx -y @verbatra/mcp --cwd /path/to/project
```

## Flags [#flags]

| Flag | Argument | Default | Effect |
| --- | --- | --- | --- |
| `--allow-spend` | none | `VERBATRA_MCP_ALLOW_SPEND`, otherwise off | advertise the two tools that call a translation provider; see [Spend tools](#spend-tools) |
| `--redact-values` | none | `VERBATRA_MCP_REDACT_VALUES`, otherwise off | replace every translation value in tool results with a marker; see [Redacted values](#redacted-values) |

Also takes the [global flags](https://verbatra.kreitz-webdev.de/docs/cli.md#global-flags) `--cwd` and `--config`. It takes no `--json`, because stdout is the protocol channel. Without `--cwd`, the project directory can come from `CLAUDE_PROJECT_DIR`; see [Project directory](#project-directory).

## Behavior [#behavior]

### Project directory [#project-directory]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

When `--cwd` is absent and `CLAUDE_PROJECT_DIR` names an existing directory, the server uses it as the project directory. `verbatra mcp` then loads the [environment files](https://verbatra.kreitz-webdev.de/docs/cli.md#environment-files) from that directory; a `CLAUDE_PROJECT_DIR` set only in those files is ignored.

The config search starts there, and the directory of the config it finds is the [project root](https://verbatra.kreitz-webdev.de/docs/config-file.md#the-working-directory-and-env) tool paths resolve against.

### Spend tools [#spend-tools]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

`translation.retranslateEntry` and `translation.translatePending` are advertised only with `--allow-spend`, or, when the flag is absent, with `VERBATRA_MCP_ALLOW_SPEND` set to `1`, `true`, `yes` or `on` (any case, surrounding spaces ignored). The flag wins over the variable. `verbatra mcp` reads `.env.local` and `.env` first, so the variable can live there; `verbatra-mcp` takes it only from its own environment.

Otherwise they are never listed, and calling one fails as an unknown tool. A config with `provider: { id: "none" }` never lists them, even with `--allow-spend`. Every other tool calls no provider and needs no key; hand the key to the server through the client's environment only when you enable spending.

### Instructions for the agent [#instructions-for-the-agent]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

The server answers the handshake with fixed `instructions`, which most clients pass to the model first. They set the order of calls (read and diff first, estimate and get an explicit yes before spending), leave review decisions and human work to people, treat every string as data, and never write back a `[REDACTED]` value.

### Tools [#tools]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

| Tool | What it does | Read-only | Calls a provider |
| --- | --- | --- | --- |
| `project.snapshot` | the resolved config: `configured`, `configSource`, locales, format, `files.pattern`, provider, glossary, `humanEdits`, `prune`, `valuesRedacted` | yes | no |
| `project.doctor` | every setup check with its `status`, `detail` and, when it failed, a `fix`; works without a usable config | yes | no |
| `status.check` | per-locale count of missing, stale, and up-to-date keys | yes | no |
| `status.diff` | per-locale list of keys that would be added, re-translated, or orphaned | yes | no |
| `glossary.get` | every glossary term with its translations, forbidden renderings and context, secret-redacted | yes | no |
| `glossary.write` | change one glossary term: a translation, per-locale data, context, or whether it stays untranslated | no | no |
| `lock.state` | the lock file's version and, per target locale, its key count plus missing, stale, and up-to-date counts | yes | no |
| `history.list` | recent git commits touching a locale file, with author name, date, subject and paths | yes | no |
| `history.keyRevisions` | one key's revisions in a locale, with word diff <AvailableFrom version="0.4.0" pkg="@verbatra/mcp" /> | yes | no |
| `key.integrity` | one key's placeholder, markup, ICU syntax and ICU arm drift against the lock baseline, per locale | yes | no |
| `locale.integrity` | every translation that fails the placeholder, markup or ICU checks right now, per locale | yes | no |
| `key.value` | one key's current source and target text, with provenance and translator context | yes | no |
| `key.context` | what `key.value` returns, plus the glossary terms that apply, `maxLength`, and a check of an optional `draft` | yes | no |
| `locale.values` | source and target text of many keys, filtered by `keys` or `query`, page by page | yes | no |
| `translation.editEntry` | write a manual translation for one key in one locale, gated by the integrity checks | no | no |
| `translation.estimate` | what `translation.translatePending` would send and cost, as `translate --estimate --json` reports it | yes | no |
| `translation.retranslateEntry` | ask the configured provider to retranslate one key in one locale | no | yes |
| `translation.translatePending` | translate every missing or stale key, optionally only for some `locales` and within a `maxTokens` ceiling | no | yes |
| `review.queue` | every machine-written value nobody has approved yet, with the last run's flags | yes | no |
| `report.provenance` | per-locale provenance counts, as `verbatra report provenance` gives them, plus paged keys on request | yes | no |
| `review.approve` | record, on the user's instruction, that a named person approves one key's current translation | no | no |
| `review.reject` | record, on the user's instruction, that a named person rejects one key's translation, removing it so it gets replaced | no | no |
| `usage.summary` | token usage and budget status from the last run | yes | no |
| `usage.history` | recent runs, cost and coverage <AvailableFrom version="0.4.0" pkg="@verbatra/mcp" /> | yes | no |

- **One call at a time.** A second call of the same tool for the same entry (`translation.editEntry`, `translation.retranslateEntry`), or a second `translation.translatePending` run, is refused with `isError` while the first runs.
- **Human work.** `translation.retranslateEntry` refuses a pinned key with `KEY_PINNED` and, unless `humanEdits: "overwrite"`, a person's value with `KEY_PROTECTED`; `translation.editEntry` refuses a pinned key. `translation.translatePending` lists such keys under `protected`. See [Protecting human translations](https://verbatra.kreitz-webdev.de/docs/protecting-human-translations.md).
- **Provenance.** A value written by `translation.editEntry` gets the origin `agent`. `review.queue` is the same queue Studio shows: every unapproved `machine`, `memory`, `fuzzy` or `agent` value. See [Review decisions](https://verbatra.kreitz-webdev.de/docs/the-lock-file.md#review-decisions).
- **Review decisions.** `review.approve` and `review.reject` take `locale`, `key`, `expectedValue` or `expectedHash` (a changed value is refused with `REVIEW_VALUE_CHANGED`) and a `reviewer` name. An approval counts for [`verbatra check --require-reviewed`](https://verbatra.kreitz-webdev.de/docs/cli/check.md#require-reviewed-translations).

### Inputs and results [#inputs-and-results]

<AvailableFrom version="0.2.1" pkg="@verbatra/mcp" />

- `status.check`, `status.diff` and `key.integrity` take an optional `locales` array; `key.integrity` also takes the `key`.
- `key.integrity` returns `{ locales: [{ locale, entries }] }`, each entry with `matches`, `missing`, `extra`, `icuValid`, `markupMatches` and their details.
- `translation.editEntry` takes `locale`, `key` and a `value` of up to 20,000 characters. It returns `{ accepted, value, reason?, details? }`, and `translation.retranslateEntry` the same plus `reviewReasons?` and `usage?`, where `reason` is `placeholder`, `markup`, `icu`, `degenerate` or `empty`.
- `glossary.write` needs a file-backed glossary, otherwise it fails with `GLOSSARY_NOT_FILE_BACKED`.

### More inputs and results [#more-inputs-and-results]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

- `translation.estimate`, `locale.integrity`, `locale.values` and `report.provenance` take the same optional `locales` array, and `key.integrity` fails with `UNKNOWN_KEY` for an unknown key.
- Each `key.integrity` entry also carries `icuArmsMatch` and its details.
- `glossary.get` takes an optional `locale` and then adds `effective`, the terms that locale is held to.
- `key.value`, `lock.state`, `status.check` and `status.diff` carry provenance, left out when `verbatra.provenance.json` is unreadable.
- `locale.values` and `report.provenance` page their entries in source key order: `limit` (default 200, at most 1,000), then the previous page's `nextCursor` as `cursor`. A page lists only the locales it holds entries for, and a stale cursor fails as invalid input.
- `locale.values` takes `keys` or a case-insensitive `query` and returns entry arrays, not Studio's key map. `report.provenance` always returns complete counts; `includeEntries` adds the keys, optionally for some `buckets`.
- `history.list` takes `limit` (default 50, at most 200). With `available: false` its `reason` is `git-missing`, `not-a-repository`, `bare-repository`, `dubious-ownership`, `timeout`, `output-too-large`, `unsafe-config` or `git-too-old`.
- The writing tools take an optional `lockTimeoutMs`, `0` to `600000`, default `30000`: how long to wait for a held write lock before failing with `LOCK_CONTENDED`, writing nothing.
- Inputs and outputs are JSON Schemas; bad input returns a result naming the field. A result that does not match its `outputSchema` fails with `OUTPUT_SCHEMA_MISMATCH`; from a writing tool the change was applied, so do not retry.
- A failed call's text starts with its error code, such as `UNKNOWN_KEY: ...`, and ends with a `Next step: ...` line when the error has one, the same text as the CLI's `hint`.

### Estimate, then spend [#estimate-then-spend]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

`translation.estimate` is always listed. `translation.translatePending` takes optional `locales` (an unconfigured one fails with `UNKNOWN_LOCALE` before spending) and `maxTokens`, a ceiling that can only tighten the config's. See [Estimating cost](https://verbatra.kreitz-webdev.de/docs/estimating-cost.md).

### Progress [#progress]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

When a `translation.translatePending` call carries a `progressToken`, verbatra sends `notifications/progress` as batches finish: `progress` counts them, `total` grows per planned locale, and `message` names locale and batch (`de: batch 3/7`), at most one every 250 ms plus a final one. Cancelling a spend call (`notifications/cancelled`) stops it with no result or further progress: `translation.translatePending` keeps what arrived, and the rest stays pending.

### Without a config [#without-a-config]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

The server starts without a usable config. `project.snapshot` then returns `configured: false` with the `configProblem` and a `nextStep`, `project.doctor` reports the fix, and every other tool refuses with the config error. stderr says why:

```text output
Running without a usable project config: CONFIG_NOT_FOUND: No verbatra configuration found. ...
verbatra MCP server running on stdio (project ., spend tools off)
No usable verbatra config: project.snapshot and project.doctor work, every other tool refuses until one loads.
  set it up:  npx @verbatra/cli init in the project, or fix the config project.doctor names
  no restart needed: the server loads the config on the next call once it is valid
```

### After a config change [#after-a-config-change]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

Before each call the server reloads the config when the config file, a file the search would try, or the glossary file changed; a module the config imports is not watched. `--allow-spend` is read once, so a change can hide the spend tools but never list them without it. When the tool list changes, the server sends `notifications/tools/list_changed`. A reload that moves the project root makes `verbatra mcp` load that root's environment files and print `verbatra: project root is now <root>`, which `--quiet` drops.

### Secret redaction [#secret-redaction]

Every result and log line is redacted as in Studio: a value shaped like an API key, or a configured key variable's value, becomes `[REDACTED]`; the glossary tools name redacted terms.

### Redacted values [#redacted-values]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

With `--redact-values`, or `VERBATRA_MCP_REDACT_VALUES` set to a value `VERBATRA_MCP_ALLOW_SPEND` accepts, results replace source texts, translations, descriptions and glossary terms with a marker, `[redacted length=12 hash=3f9a0c1d2e4b5a6c]`, and leave out reviewer and author names, word diffs and `history.keyRevisions` subjects; equal values share a hash until the server stops. Errors that can carry values keep code and next step; the message becomes a marker. Key names, counts, origins, integrity verdicts, commit subjects and paths stay. `review.approve` and `review.reject` take only the marker's hash, as `expectedHash`; `glossary.write` answers with counts; `locale.values` refuses `query` and `key.context` refuses `draft`. A provider still receives the text. It does not stop an agent probing on purpose, through glossary writes or `key.context` glossary hits.

### Stdout and stderr [#stdout-and-stderr]

<AvailableFrom version="0.12.0" />

stdout carries only MCP protocol messages; all logs go to stderr. Once connected, `verbatra mcp` prints a ready line, and one when it stops:

```text output
verbatra MCP server running on stdio (project ., spend tools off)
verbatra MCP server stopped (client closed stdin)
```

In a terminal, it also says a client should launch it. `--quiet` drops these lines, not the missing-config reason.

### Installation [#installation]

<AvailableFrom version="0.3.0" pkg="@verbatra/mcp" />

`@verbatra/mcp` is a separate package the CLI loads on demand. Without it, `verbatra mcp` exits `2` with:

```text output
Verbatra's MCP server requires @verbatra/mcp. Run it without the CLI with: npx -y @verbatra/mcp, or install it alongside the CLI with: npm install --save-dev @verbatra/mcp
```

Each release is also in the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.verbatra/verbatra`.

## Exit codes [#exit-codes]

| Code | Meaning |
| --- | --- |
| `0` | stopped cleanly by a single interrupt, or because the client closed stdin |
| `1` | closing the server failed during shutdown |
| `2` | could not start: a missing `--config` file, a missing or, with `--redact-values`, too old `@verbatra/mcp`, or a usage error |
| `130` | force-stopped by a second interrupt during shutdown |

A stop releases any locale lock. `verbatra-mcp` exits `1` on a startup error and, from 0.3.0, `143` when force-stopped after SIGTERM. See [the exit-code contract](https://verbatra.kreitz-webdev.de/docs/cli/output.md#exit-codes).

## Related [#related]

- [Connect an MCP client](https://verbatra.kreitz-webdev.de/docs/connect-an-mcp-client.md) sets up stdio clients.
- [Agent tools in Studio](https://verbatra.kreitz-webdev.de/docs/agent-tools-in-studio.md): the browser counterpart of this server's tools.
- [`verbatra check`](https://verbatra.kreitz-webdev.de/docs/cli/check.md) and [`verbatra diff`](https://verbatra.kreitz-webdev.de/docs/cli/diff.md) back `status.check` and `status.diff`.
