verbatra

@verbatra/mcp

Stdio MCP server exposing verbatra's translation status, glossary, and editing capabilities as tools for any MCP client, without a browser.

Documentation | Connect a client | Changelog | Issues

Description

@verbatra/mcp starts a Model Context Protocol server over stdio, the standard local-process transport an MCP client uses to launch and talk to a tool server. It gives a terminal-hosted or headless agent the same translation-status, glossary, and editing capabilities Verbatra Studio exposes in the browser, without a browser, a port, or a served single-page app. It is a thin, SDK-backed surface over @verbatra/sdk, the same way @verbatra/cli is.

Installation

Most MCP clients spawn the server for you and need no local install at all: point the client at npx -y @verbatra/mcp and npx fetches it on demand. To pin it in your project instead:

npm install --save-dev @verbatra/mcp

Needs Node.js ^22.18.0 || >=24. The server is also reachable through verbatra mcp once both @verbatra/cli and @verbatra/mcp are installed.

Configuring an MCP client

Point your client at the verbatra-mcp binary, which the @verbatra/mcp package provides (the example runs it through npx). The shape below is the one most clients use; for an editor or desktop client, put it in that client's MCP server configuration file.

{

"mcpServers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp", "--cwd", "/path/to/your/project"], "env": {} } } }

In Claude Code, npx @verbatra/cli init --agent (or claude mcp add --transport stdio --scope project verbatra -- npx -y @verbatra/mcp) writes an equivalent entry to a committed .mcp.json. The verbatra plugin bundles the agent skills with its own copy of this server, so use it instead of the .mcp.json entry, never both: together they register the server twice. VS Code (GitHub Copilot's agent mode) reads .vscode/mcp.json, whose top-level key is servers rather than mcpServers. The exact file, key, and working-directory handling for every client is in Connect an MCP client.

That configuration is read-only plus local editing: no provider is called and no API key is needed. Add --allow-spend to args, and the environment variable your configured provider reads its key from, once you also want the two provider-calling tools. --config loads a specific config file instead of searching for one, and VERBATRA_MCP_ALLOW_SPEND is the environment equivalent of the flag, which the flag always wins over.

Tools

Every tool, listed in the order the server advertises them.

Security and spend

• Spend is opt-in. translation.retranslateEntry and translation.translatePending are the two tools that call a provider. They are advertised only when the server is started with --allow-spend or VERBATRA_MCP_ALLOW_SPEND; without either, a client never sees them and calling one by name fails as an unknown tool. A config with provider: { id: "none" } never lists them, even with --allow-spend.
• Values can stay home. --redact-values (or VERBATRA_MCP_REDACT_VALUES) replaces every source text, translation, description, and glossary term in a result with a marker such as [redacted length=12 hash=3f9a0c1d2e4b5a6c], and leaves out reviewer and author names. Key names, counts, statuses, and integrity verdicts stay. review.approve and review.reject then take only the marker's hash as expectedHash, locale.values refuses query, and key.context refuses draft. This keeps values out of results; it does not stop an agent that probes on purpose, and what a provider receives does not change.
• Secrets are scrubbed. Every result and log line passes through a redaction pass first, so a value shaped like a provider API key, or the exact value of a configured provider variable, becomes [REDACTED] before it reaches the client or stderr.
• Stdout is protocol only. Nothing but MCP messages is written to stdout; every log and diagnostic line goes to stderr.
• Config changes need no restart. The server starts without a usable config (project.snapshot reports configured: false, project.doctor says what to fix) and reloads the config and its glossary file before each call. --allow-spend is fixed at startup, and a config change never widens it.

Every tool's input, and every closed-shape tool output, is a JSON Schema derived from the same zod schema the server validates the call against. See the verbatra mcp docs for the full tool reference, the exit-code contract, and worked examples.

Documentation

• verbatra mcp reference
• Connect an MCP client
• Agent recipes

Related packages

• @verbatra/sdk: the engine this server is a thin surface over.
• @verbatra/cli: the verbatra command, including verbatra mcp.
• @verbatra/studio: the same capabilities in a browser dashboard.

Contributing

See CONTRIBUTING.md.

License

MIT (c) Mario Kreitz