--- title: "Connect an MCP client" description: "Wire verbatra's stdio MCP server into your coding agent or any other MCP client, with the provider key kept out of every committed file." type: "how-to" --- # Connect an MCP client Wire verbatra's stdio MCP server into your coding agent or any other MCP client, with the provider key kept out of every committed file. Start here: once `@verbatra/cli` is installed in the project, `npx @verbatra/cli init --agent` wires your coding agent, spending off. Let a coding agent read translation status and fix values through verbatra's stdio MCP server. Register it once per client: a second entry starts a second server. You need a project with a verbatra config ([`npx @verbatra/cli init`](https://verbatra.kreitz-webdev.de/docs/cli/init.md)) and Node.js `^22.18.0 || >=24`. ## Pick a launch command [#pick-a-launch-command] | Command | Needs | Reads `.env` files | | --- | --- | --- | | `npx -y @verbatra/mcp` | nothing installed | no | | `npx @verbatra/cli mcp` | `@verbatra/cli` and `@verbatra/mcp` as dev dependencies | yes: `.env.local`, then `.env` | Avoid `npx -y @verbatra/cli mcp`, which exits `2` because the CLI never installs `@verbatra/mcp`. [Project directory](https://verbatra.kreitz-webdev.de/docs/cli/mcp.md#project-directory) says where the server looks for the config. ### MCP Registry [#mcp-registry] It is also in the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.verbatra/verbatra`. ## Decide whether the agent may spend [#decide-whether-the-agent-may-spend] The server starts with read and local edit tools only: spend tools stay hidden and no tool reads a key. To let the agent spend, add both: - `--allow-spend` in the arguments, or `VERBATRA_MCP_ALLOW_SPEND=1` in the environment ([Spend tools](https://verbatra.kreitz-webdev.de/docs/cli/mcp.md#spend-tools)); - your provider's key variable, such as `ANTHROPIC_API_KEY` ([Providers](https://verbatra.kreitz-webdev.de/docs/providers.md)). Never write a key into a committed file such as `.mcp.json`, `.codex/config.toml`, `.gemini/settings.json`, `.cursor/mcp.json` or `.vscode/mcp.json`. To keep values from the agent's model, add `--redact-values`; see [Studio and MCP](https://verbatra.kreitz-webdev.de/docs/data-handling.md#studio-and-mcp). ### Estimate first [#estimate-first] The server still tells the agent to run `translation.estimate` and wait for your yes before spending. ## Claude Code [#claude-code] ### Let init write it [#let-init-write-it] Recommended, from the project root: ```bash npx @verbatra/cli init --agent ``` [`init --agent`](https://verbatra.kreitz-webdev.de/docs/cli/init.md#set-up-coding-agents) writes the agent instruction file and, spending off, this entry to the committed `.mcp.json` when it finds Claude Code (`CLAUDE.md`, `.claude/` or `.mcp.json`) or no client at all; `--client claude` forces it: ```json { "mcpServers": { "verbatra": { "type": "stdio", "command": "npx", "args": ["-y", "@verbatra/mcp"] } } } ``` Restart Claude Code and approve the `verbatra` server; it passes `CLAUDE_PROJECT_DIR` and your environment. To spend for one session, export the key and run: ```bash VERBATRA_MCP_ALLOW_SPEND=1 claude ``` `claude mcp list` checks the connection. See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp). ### Other routes [#other-routes] #### Without the CLI [#without-the-cli] ```bash claude mcp add --transport stdio --scope project verbatra -- npx -y @verbatra/mcp ``` This writes the same entry. Never add `--env KEY=value` here: it writes the value into `.mcp.json`. #### The verbatra plugin [#the-verbatra-plugin] Instead of `.mcp.json`, the plugin bundles the [verbatra skills](https://verbatra.kreitz-webdev.de/docs/agent-recipes.md#the-skills-pack), this server, and a hook that checks a locale file after Claude edits it. Never combine the verbatra plugin with a `verbatra` entry in `.mcp.json`: the plugin brings a second server. `init --agent` skips the entry when the plugin is enabled in `.claude/settings.json` or `.claude/settings.local.json`. ```bash claude plugin marketplace add verbatra/skills claude plugin install verbatra@verbatra --scope project ``` - **Server**: a pinned `@verbatra/mcp` with `--cwd` set to the open project. - **Spending**: off until you turn on the plugin's `allowSpend` option (`--config allowSpend=true`, or `/config`). A committed file cannot turn it on. - **Key**: from the environment you started `claude` with. - **Hook**: runs the project's `verbatra check --file ` (CLI 0.12.0 or later) and reports broken placeholders, markup or ICU, calling no provider. See the [Claude Code plugins reference](https://code.claude.com/docs/en/plugins-reference). ## Codex [#codex] Recommended: `npx @verbatra/cli init --agent --client codex` (or plain `init --agent` when `.codex/` exists) appends this table to `.codex/config.toml`, spending off: ```toml title=".codex/config.toml" [mcp_servers.verbatra] command = "npx" args = ["-y", "@verbatra/mcp"] startup_timeout_sec = 60 ``` Codex loads it only once you answer **Trust this folder?**, which covers the repository root. From a subfolder, the server roots at the config it finds. See the [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). ### Codex user config [#codex-user-config] To spend, use `~/.codex/config.toml` instead. `env_vars` passes variables by name; an `env` table or `codex mcp add --env` stores the value: ```toml title="~/.codex/config.toml" [mcp_servers.verbatra] command = "npx" args = ["-y", "@verbatra/mcp", "--allow-spend"] cwd = "/path/to/your/project" env_vars = ["ANTHROPIC_API_KEY"] ``` ## Gemini CLI [#gemini-cli] Recommended: `npx @verbatra/cli init --agent --client gemini` (or plain `init --agent` when `.gemini/` or `GEMINI.md` exists) adds this entry to `.gemini/settings.json`, spending off: ```json title=".gemini/settings.json" { "mcpServers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp"] } } } ``` Gemini CLI reads it only from the folder it starts in: start `gemini` in the project root and trust it in the dialog or with `/permissions trust`. Leave `trust` unset; `/mcp` lists the tools. It reads `GEMINI.md`, not `AGENTS.md`: add `"context": { "fileName": ["AGENTS.md", "GEMINI.md"] }` to the settings or `@AGENTS.md` to `GEMINI.md`. See the [Gemini CLI MCP documentation](https://geminicli.com/docs/tools/mcp-server/). ### Gemini CLI user settings [#gemini-cli-user-settings] To spend, use your user settings with an absolute `cwd`: ```json title="~/.gemini/settings.json" { "mcpServers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp", "--allow-spend"], "cwd": "/path/to/your/project", "env": { "ANTHROPIC_API_KEY": "$ANTHROPIC_API_KEY" } } } } ``` Gemini CLI hides key variables from servers, so pass the key through `env`. ## Cursor [#cursor] `init --agent` writes Cursor's `.cursor/mcp.json` when it finds `.cursor/` or `.cursorrules`, or with `--client cursor`: ```json title=".cursor/mcp.json" { "mcpServers": { "verbatra": { "type": "stdio", "command": "npx", "args": ["-y", "@verbatra/mcp", "--cwd", "${workspaceFolder}"] } } } ``` To spend, append `"--allow-spend"` to `args` and add `"env": { "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}" }`. See the [Cursor MCP documentation](https://cursor.com/docs/mcp). ## VS Code [#vs-code] VS Code (GitHub Copilot's agent mode) reads `.vscode/mcp.json`, keyed `servers`, which `init --agent --client vscode` writes. Without `--client`, `init --agent` wires it only when that file exists and prints the command for a bare `.vscode/` folder. It needs no `--cwd`: ```json title=".vscode/mcp.json" { "servers": { "verbatra": { "type": "stdio", "command": "npx", "args": ["-y", "@verbatra/mcp"] } } } ``` To spend, declare the key as an input, which VS Code stores outside the file: ```json title=".vscode/mcp.json" { "inputs": [ { "type": "promptString", "id": "anthropic-key", "description": "Anthropic API key", "password": true } ], "servers": { "verbatra": { "type": "stdio", "command": "npx", "args": ["-y", "@verbatra/mcp", "--allow-spend"], "env": { "ANTHROPIC_API_KEY": "${input:anthropic-key}" } } } } ``` [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22verbatra%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40verbatra%2Fmcp%22%5D%7D) Instead of the file, the button or this command adds it to your user profile, spending off; use one route, never two: ```bash code --add-mcp '{"name":"verbatra","command":"npx","args":["-y","@verbatra/mcp"]}' ``` See the [VS Code MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). ## GitHub Copilot [#github-copilot] ### Copilot cloud agent [#copilot-cloud-agent] A repository admin adds the server under **Settings**, **Copilot**, **MCP servers**. The cloud agent calls tools without asking, so list only tools that neither write nor call a provider: ```json { "mcpServers": { "verbatra": { "type": "local", "command": "npx", "args": ["-y", "@verbatra/mcp"], "tools": [ "project.snapshot", "project.doctor", "status.check", "status.diff", "glossary.get", "lock.state", "history.list", "key.integrity", "locale.integrity", "key.value", "key.context", "locale.values", "translation.estimate", "review.queue", "report.provenance", "usage.summary" ] } } } ``` Add `translation.editEntry` and `glossary.write` only if the agent should write in its pull request, and keep `review.approve` and `review.reject` out: a review decision needs a person. To check, open **View session** and expand **Start MCP Servers**. See [Extending the cloud agent with MCP](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers). ### Copilot CLI [#copilot-cli] ```bash copilot mcp add verbatra -- npx -y @verbatra/mcp --cwd /path/to/your/project ``` This writes `~/.copilot/mcp-config.json`. Copilot CLI passes a server only `PATH`, so a key goes into that entry's `env`, never into a project file. See [Adding MCP servers to Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). ## Windsurf [#windsurf] Windsurf reads one `mcp_config.json` for all projects, so `--cwd` is absolute: ```json title="mcp_config.json" { "mcpServers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp", "--cwd", "/path/to/your/project"] } } } ``` To spend, append `"--allow-spend"` and add `"env": { "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}" }`. See the [Cascade MCP documentation](https://docs.devin.ai/desktop/cascade/mcp). ## Zed [#zed] Zed reads `context_servers` from its settings; **Settings**, **AI**, **MCP Servers**, **Add Server** writes the entry: ```json title="settings.json" { "context_servers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp", "--cwd", "/path/to/your/project"], "env": {} } } } ``` A key in `env` is a literal value, so add it and `--allow-spend` only in your user settings, never in `.zed/settings.json`. See the [Zed MCP documentation](https://zed.dev/docs/ai/mcp). ## JetBrains AI Assistant [#jetbrains-ai-assistant] Open **Settings**, **Tools**, **AI Assistant**, **Model Context Protocol (MCP)**, add a server, and paste: ```json { "mcpServers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp"] } } } ``` Set **Working directory** to the project root and keep this entry no-spend. See the [AI Assistant MCP documentation](https://www.jetbrains.com/help/ai-assistant/mcp.html). ## Claude Desktop [#claude-desktop] **Settings**, **Developer**, **Edit Config** opens `claude_desktop_config.json`. There is no project, so `--cwd` is absolute: ```json title="claude_desktop_config.json" { "mcpServers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp", "--cwd", "/path/to/your/project"] } } } ``` To spend, append `"--allow-spend"` and add `"env": { "ANTHROPIC_API_KEY": "..." }`, then restart Claude Desktop. See [Connect to local MCP servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers). ## Any other stdio client [#any-other-stdio-client] Give the client the command `npx -y @verbatra/mcp`, plus `--cwd /path/to/your/project` unless it starts servers inside the project, and `--config ` for a config elsewhere. Pass `--allow-spend` and the key only through the client's secret mechanism. ## Check the connection [#check-the-connection] Ask the agent to call `project.snapshot`; it returns the locales, format and provider without calling it. - **`configured: false`**: no usable config was found. Ask for `project.doctor`, then run `npx @verbatra/cli init` or fix `--cwd`. See [Without a config](https://verbatra.kreitz-webdev.de/docs/cli/mcp.md#without-a-config). - **Spend tools missing**: check the spend switch and whether the provider is `none`. - **Config edited**: no restart needed; see [After a config change](https://verbatra.kreitz-webdev.de/docs/cli/mcp.md#after-a-config-change). ## Related [#related] - [`verbatra mcp`](https://verbatra.kreitz-webdev.de/docs/cli/mcp.md): flags and every tool. - [Script verbatra with JSON](https://verbatra.kreitz-webdev.de/docs/agent-recipes.md#the-skills-pack): the `verbatra-mcp-tools` skill.