--- title: "Conectar un cliente MCP" description: "Conecta el servidor MCP stdio de verbatra a tu agente de código o a cualquier otro cliente MCP, sin que la clave del proveedor acabe en el repositorio." type: "how-to" --- # Conectar un cliente MCP Conecta el servidor MCP stdio de verbatra a tu agente de código o a cualquier otro cliente MCP, sin que la clave del proveedor acabe en el repositorio. Empieza aquí: en cuanto `@verbatra/cli` esté instalado en el proyecto, `npx @verbatra/cli init --agent` conecta tu agente de programación, sin gasto. Deja que un agente de programación lea el estado de las traducciones y corrija valores a través del servidor MCP stdio de verbatra. Regístralo una vez por cliente: una segunda entrada arranca un segundo servidor. Necesitas un proyecto con configuración de verbatra ([`npx @verbatra/cli init`](https://verbatra.kreitz-webdev.de/es/docs/cli/init.md)) y Node.js `^22.18.0 || >=24`. ## Elige un comando de inicio [#elige-un-comando-de-inicio] | Comando | Necesita | Lee archivos `.env` | | --- | --- | --- | | `npx -y @verbatra/mcp` | nada instalado | no | | `npx @verbatra/cli mcp` | `@verbatra/cli` y `@verbatra/mcp` como dependencias de desarrollo | sí: `.env.local` y luego `.env` | Evita `npx -y @verbatra/cli mcp`, que termina con `2` porque la CLI nunca instala `@verbatra/mcp`. [Directorio del proyecto](https://verbatra.kreitz-webdev.de/es/docs/cli/mcp.md#directorio-del-proyecto) explica dónde busca el servidor la configuración. ### Registro de MCP [#registro-de-mcp] El servidor también aparece en el [registro oficial de MCP](https://registry.modelcontextprotocol.io) como `io.github.verbatra/verbatra`. ## Decide si el agente puede gastar [#decide-si-el-agente-puede-gastar] El servidor arranca solo con herramientas de lectura y edición local: las herramientas de gasto quedan ocultas y ninguna herramienta lee una clave. Para que el agente pueda gastar, añade las dos cosas: - `--allow-spend` en los argumentos, o `VERBATRA_MCP_ALLOW_SPEND=1` en el entorno ([Herramientas de gasto](https://verbatra.kreitz-webdev.de/es/docs/cli/mcp.md#herramientas-de-gasto)); - la variable de la clave de tu proveedor, como `ANTHROPIC_API_KEY` ([Proveedores](https://verbatra.kreitz-webdev.de/es/docs/providers.md)). Nunca escribas una clave en un archivo del repositorio como `.mcp.json`, `.codex/config.toml`, `.gemini/settings.json`, `.cursor/mcp.json` o `.vscode/mcp.json`. Para que los valores de traducción no lleguen al modelo del agente, añade `--redact-values`; consulta [Studio y MCP](https://verbatra.kreitz-webdev.de/es/docs/data-handling.md#studio-y-mcp). ### Primero estimar [#primero-estimar] Aun así, el servidor le indica al agente que ejecute `translation.estimate` y espere tu sí antes de gastar. ## Claude Code [#claude-code] ### Deja que init lo escriba [#deja-que-init-lo-escriba] Recomendado, desde la raíz del proyecto: ```bash npx @verbatra/cli init --agent ``` [`init --agent`](https://verbatra.kreitz-webdev.de/es/docs/cli/init.md#preparar-los-agentes-de-programación) escribe el archivo de instrucciones para agentes y, con el gasto desactivado, esta entrada en el `.mcp.json` del repositorio cuando encuentra Claude Code (`CLAUDE.md`, `.claude/` o `.mcp.json`) o ningún cliente; `--client claude` la fuerza: ```json { "mcpServers": { "verbatra": { "type": "stdio", "command": "npx", "args": ["-y", "@verbatra/mcp"] } } } ``` Reinicia Claude Code y aprueba el servidor `verbatra`; Claude Code le transmite `CLAUDE_PROJECT_DIR` y tu entorno. Para gastar en una sesión, exporta la clave y ejecuta: ```bash VERBATRA_MCP_ALLOW_SPEND=1 claude ``` `claude mcp list` comprueba la conexión. Consulta la [documentación de MCP de Claude Code](https://code.claude.com/docs/en/mcp). ### Otras vías [#otras-vías] #### Sin la CLI [#sin-la-cli] ```bash claude mcp add --transport stdio --scope project verbatra -- npx -y @verbatra/mcp ``` Esto escribe la misma entrada. Nunca añadas `--env KEY=value` aquí: escribe el valor en `.mcp.json`. #### El plugin de verbatra [#el-plugin-de-verbatra] En lugar de `.mcp.json`, el plugin reúne las [skills de verbatra](https://verbatra.kreitz-webdev.de/es/docs/agent-recipes.md#el-paquete-de-skills), este servidor y un hook que revisa un archivo de locale después de que Claude lo edite. Nunca combines el plugin de verbatra con una entrada `verbatra` en `.mcp.json`: el plugin trae un segundo servidor. `init --agent` omite la entrada cuando el plugin está activado en `.claude/settings.json` o `.claude/settings.local.json`. ```bash claude plugin marketplace add verbatra/skills claude plugin install verbatra@verbatra --scope project ``` - **Servidor**: un `@verbatra/mcp` de versión fija con `--cwd` en el proyecto abierto. - **Gasto**: desactivado hasta que actives la opción `allowSpend` del plugin (`--config allowSpend=true`, o `/config`). Un archivo del repositorio no puede activarla. - **Clave**: del entorno con el que arrancaste `claude`. - **Hook**: ejecuta el `verbatra check --file ` del proyecto (CLI 0.12.0 o posterior) e informa de placeholders, markup o ICU rotos, sin llamar a ningún proveedor. Consulta la [referencia de plugins de Claude Code](https://code.claude.com/docs/en/plugins-reference). ## Codex [#codex] Lo recomendado: `npx @verbatra/cli init --agent --client codex` (o `init --agent` a secas cuando existe `.codex/`) añade esta tabla al final de `.codex/config.toml`, con el gasto desactivado: ```toml title=".codex/config.toml" [mcp_servers.verbatra] command = "npx" args = ["-y", "@verbatra/mcp"] startup_timeout_sec = 60 ``` Codex solo la carga cuando respondes a **Trust this folder?**, que cubre la raíz del repositorio. Si arrancas desde una subcarpeta, el servidor se sitúa en la configuración que encuentra. Consulta la [documentación de MCP de Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). ### Configuración de usuario de Codex [#configuración-de-usuario-de-codex] Para gastar, usa `~/.codex/config.toml` en su lugar. `env_vars` transmite variables por su nombre; una tabla `env` o `codex mcp add --env` guarda el valor: ```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] Lo recomendado: `npx @verbatra/cli init --agent --client gemini` (o `init --agent` a secas cuando existe `.gemini/` o `GEMINI.md`) añade esta entrada a `.gemini/settings.json`, con el gasto desactivado: ```json title=".gemini/settings.json" { "mcpServers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp"] } } } ``` Gemini CLI solo la lee de la carpeta en la que arranca: inicia `gemini` en la raíz del proyecto y dale confianza en el diálogo o con `/permissions trust`. Deja `trust` sin definir; `/mcp` muestra las herramientas. Lee `GEMINI.md`, no `AGENTS.md`: añade `"context": { "fileName": ["AGENTS.md", "GEMINI.md"] }` a los ajustes o `@AGENTS.md` a `GEMINI.md`. Consulta la [documentación de MCP de Gemini CLI](https://geminicli.com/docs/tools/mcp-server/). ### Ajustes de usuario de Gemini CLI [#ajustes-de-usuario-de-gemini-cli] Para gastar, usa tus ajustes de usuario con un `cwd` absoluto: ```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 oculta a los servidores las variables de claves, así que pasa la clave por `env`. ## Cursor [#cursor] `init --agent` escribe el `.cursor/mcp.json` de Cursor cuando encuentra `.cursor/` o `.cursorrules`, o con `--client cursor`: ```json title=".cursor/mcp.json" { "mcpServers": { "verbatra": { "type": "stdio", "command": "npx", "args": ["-y", "@verbatra/mcp", "--cwd", "${workspaceFolder}"] } } } ``` Para gastar, añade `"--allow-spend"` al final de `args` y agrega `"env": { "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}" }`. Consulta la [documentación de MCP de Cursor](https://cursor.com/docs/mcp). ## VS Code [#vs-code] VS Code (el modo agente de GitHub Copilot) lee `.vscode/mcp.json`, con la clave `servers`, que escribe `init --agent --client vscode`. Sin `--client`, `init --agent` solo lo conecta cuando ese archivo ya existe e imprime el comando para una carpeta `.vscode/` sin él. No hace falta `--cwd`: ```json title=".vscode/mcp.json" { "servers": { "verbatra": { "type": "stdio", "command": "npx", "args": ["-y", "@verbatra/mcp"] } } } ``` Para gastar, declara la clave como input, que VS Code guarda fuera del archivo: ```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}" } } } } ``` [Añadir a 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) En lugar del archivo, el botón o este comando añade la entrada sin gasto a tu perfil de usuario; usa una de las tres vías, nunca dos: ```bash code --add-mcp '{"name":"verbatra","command":"npx","args":["-y","@verbatra/mcp"]}' ``` Consulta la [referencia de configuración de MCP de VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). ## GitHub Copilot [#github-copilot] ### Copilot cloud agent [#copilot-cloud-agent] Una persona administradora del repositorio añade el servidor en **Settings**, **Copilot**, **MCP servers**. El cloud agent llama a las herramientas sin preguntar, así que lista solo las que ni escriben ni llaman a un proveedor: ```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" ] } } } ``` Añade `translation.editEntry` y `glossary.write` solo si el agente debe escribir en su pull request, y deja fuera `review.approve` y `review.reject`: una decisión de revisión necesita a una persona. Para comprobarlo, abre **View session** y despliega **Start MCP Servers**. Consulta [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 ``` Esto escribe `~/.copilot/mcp-config.json`. Copilot CLI solo le pasa `PATH` a un servidor, así que una clave va en el `env` de esa entrada, nunca en un archivo del proyecto. Consulta [Adding MCP servers to Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). ## Windsurf [#windsurf] Windsurf lee un único `mcp_config.json` para todos los proyectos, así que `--cwd` es absoluto: ```json title="mcp_config.json" { "mcpServers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp", "--cwd", "/path/to/your/project"] } } } ``` Para gastar, añade `"--allow-spend"` al final y agrega `"env": { "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}" }`. Consulta la [documentación de MCP de Cascade](https://docs.devin.ai/desktop/cascade/mcp). ## Zed [#zed] Zed lee `context_servers` de sus ajustes; **Settings**, **AI**, **MCP Servers**, **Add Server** escribe la entrada: ```json title="settings.json" { "context_servers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp", "--cwd", "/path/to/your/project"], "env": {} } } } ``` Una clave en `env` es un valor literal, así que añádela junto con `--allow-spend` solo en tus ajustes de usuario, nunca en `.zed/settings.json`. Consulta la [documentación de MCP de Zed](https://zed.dev/docs/ai/mcp). ## JetBrains AI Assistant [#jetbrains-ai-assistant] Abre **Settings**, **Tools**, **AI Assistant**, **Model Context Protocol (MCP)**, añade un servidor y pega: ```json { "mcpServers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp"] } } } ``` Pon **Working directory** en la raíz del proyecto y deja esta entrada sin gasto. Consulta la [documentación de MCP de AI Assistant](https://www.jetbrains.com/help/ai-assistant/mcp.html). ## Claude Desktop [#claude-desktop] **Settings**, **Developer**, **Edit Config** abre `claude_desktop_config.json`. No hay proyecto, así que `--cwd` es absoluto: ```json title="claude_desktop_config.json" { "mcpServers": { "verbatra": { "command": "npx", "args": ["-y", "@verbatra/mcp", "--cwd", "/path/to/your/project"] } } } ``` Para gastar, añade `"--allow-spend"` al final y agrega `"env": { "ANTHROPIC_API_KEY": "..." }` y después reinicia Claude Desktop. Consulta [Connect to local MCP servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers). ## Cualquier otro cliente stdio [#cualquier-otro-cliente-stdio] Dale al cliente el comando `npx -y @verbatra/mcp`, más `--cwd /path/to/your/project` salvo que arranque los servidores dentro del proyecto, y `--config ` si la configuración está en otro sitio. Añade `--allow-spend` y la clave solo mediante el mecanismo de secretos del propio cliente. ## Comprueba la conexión [#comprueba-la-conexión] Pídele al agente que llame a `project.snapshot`, que devuelve los locales, el formato y el proveedor sin llamarlo. - **`configured: false`**: no se encontró una configuración utilizable. Pide `project.doctor` y luego ejecuta `npx @verbatra/cli init` o corrige `--cwd`. Consulta [Sin configuración](https://verbatra.kreitz-webdev.de/es/docs/cli/mcp.md#sin-configuración). - **Faltan las herramientas de gasto**: revisa el interruptor de gasto y si el proveedor es `none`. - **Configuración editada**: no hace falta reiniciar; consulta [Tras un cambio de configuración](https://verbatra.kreitz-webdev.de/es/docs/cli/mcp.md#tras-un-cambio-de-configuración). ## Relacionado [#relacionado] - [`verbatra mcp`](https://verbatra.kreitz-webdev.de/es/docs/cli/mcp.md): flags y cada herramienta. - [Programa verbatra con JSON](https://verbatra.kreitz-webdev.de/es/docs/agent-recipes.md#el-paquete-de-skills): la skill `verbatra-mcp-tools`.