Claude Code: añade servidores MCP sin exponer tokens

¿Pegas tu token de MCP directo en la terminal? 🔑 Claude Code 2.1.327 permite pasar el JSON por stdin con add-json y no dejarlo en el comando. Guía paso a paso #ClaudeCode

Tarjeta con el título "Añade servidores MCP sin exponer tus tokens" sobre fondo azul oscuro

Desde la versión 2.1.327 de Claude Code puedes ejecutar claude mcp add-json <nombre> - y pasar la configuración del servidor MCP por la entrada estándar (stdin). La ventaja práctica es que un token o una clave ya no tiene que escribirse dentro del comando, donde queda en el historial de la terminal. Aquí ves cómo usarlo, qué otras opciones existen y qué límites tiene.

Qué cambió en Claude Code 2.1.327

El changelog oficial de Claude Code en GitHub describe tres cambios relacionados con MCP en la versión 2.1.327. El primero es el protagonista de esta guía: claude mcp add-json acepta un guion (-) en lugar del JSON y lee la configuración desde stdin. El changelog advierte que esta forma no está disponible dentro de una sesión de Claude Code, así que se ejecuta desde tu terminal normal.

Los otros dos cambios protegen tu archivo .mcp.json. Con --scope project, el comando se detiene en lugar de sobrescribir el archivo si los servidores están en el nivel superior sin la clave mcpServers. Además, se corrigió un fallo por el que claude mcp add y claude mcp remove con alcance de proyecto borraban otras claves de nivel superior, como $schema o la sección servers de otra herramienta.

Una aclaración sobre fechas: el changelog de GitHub no publica fecha para cada versión, así que no podemos decir con exactitud qué día salió la 2.1.327. Lo verificable es que figura como la entrada más reciente que leímos el 18 de noviembre de 2026. La página de documentación de MCP, además, aún no describe la forma con stdin, por lo que la fuente de este detalle es el changelog.

Requisitos

  • Claude Code actualizado a la versión 2.1.327 o posterior (compruébalo con claude --version).
  • Un servidor MCP que quieras conectar y que requiera un secreto, por ejemplo un token de API.
  • Una terminal normal, fuera de una sesión de Claude Code.

Paso a paso: añadir un servidor MCP sin exponer el token

1. La forma clásica y su problema

La documentación oficial muestra add-json con el JSON escrito directamente como argumento. Es cómodo, pero si el JSON lleva un token, ese texto queda en el historial de tu shell y puede verse en la lista de procesos mientras corre el comando.

claude mcp add-json events-server '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

Ese ejemplo viene de la documentación oficial. Observa que el token va dentro del comando.

2. La forma nueva con stdin

Con la versión 2.1.327 puedes enviar el JSON por una tubería y dejar un guion donde iba el argumento. El siguiente ejemplo lo armamos nosotros a partir de la sintaxis del changelog y de los campos que documenta Anthropic; no lo ejecutamos. Usa un servidor ficticio, así que cambia el nombre y la URL por los de tu servicio.

# Lee el token sin mostrarlo en pantalla (bash)
read -rs MI_TOKEN

# printf es un comando interno del shell: el token no aparece como argumento de un proceso
printf '{"type":"http","url":"https://api.example.com/mcp","headers":{"Authorization":"Bearer %s"}}' "$MI_TOKEN" \
  | claude mcp add-json mi-api -

unset MI_TOKEN

Dos detalles útiles: read -rs oculta lo que escribes, y el printf de bash es un comando interno, de modo que el token no viaja en los argumentos de ningún programa externo. Esto último es razonamiento nuestro sobre cómo funciona el shell, no una afirmación de la documentación de Claude Code.

3. Comprueba que quedó bien

La documentación indica que cada add y add-json imprime una línea “Added …” al terminar bien, y que claude mcp get sirve para verificar la conexión.

claude mcp list
claude mcp get mi-api

Para quitarlo más adelante usa claude mcp remove mi-api. Según la documentación, al quitar un servidor remoto Claude Code también borra los tokens OAuth y el registro de cliente que había guardado para él.

4. Elige bien el alcance

La documentación acepta --scope project o --scope user en add-json; si no indicas nada, el alcance es local. Si usas project, el servidor se escribe en .mcp.json, un archivo pensado para compartirse en el repositorio. Por eso un token real nunca debería terminar ahí: en esa configuración compartida conviene referenciar variables de entorno. La documentación también describe la expansión de ${VAR} y ${VAR:-valor} en campos como la URL o los encabezados (esta parte la leímos en un resumen de la página, así que confírmala en la documentación antes de depender de ella).

Cómo interpretarlo: qué opción usar

OpciónDónde puede quedar el secretoCuándo conviene
add-json con JSON como argumentoEn el historial del shell y en los argumentos del procesoPruebas con servidores sin secretos
add-json <nombre> - con stdinSolo en la tubería y en memoria del shell, aunque luego Claude Code lo guarda en su configuraciónServidores con token que añades desde tu terminal
.mcp.json con variables ${VAR}En tu entorno, no en el archivoServidores compartidos con el equipo

Fíjate en la matiz de la segunda fila: stdin evita dejar el token en el historial, pero el servidor se guarda en la configuración de Claude Code, y esa configuración puede contener el valor. Tampoco sustituye la revisión de qué servidor instalas. La propia documentación avisa de que conviene confiar en cada servidor antes de conectarlo.

Seguridad y costos

Añadir un servidor MCP no tiene costo por sí mismo, pero sí amplía lo que Claude puede hacer: un servidor remoto recibe tus peticiones y puede devolver datos que entran en el contexto. Antes de conectarlo, comprueba quién lo mantiene y qué permisos le das al token (mejor uno de solo lectura). Si quieres limitar lo que ocurre en tu máquina, combina esto con un buen control de comandos; tenemos guías sobre hooks para bloquear y automatizar acciones y sobre el sandbox de Bash.

Qué significa para quien programa

Es un cambio pequeño con efecto real en tu rutina: añadir servidores con credenciales deja de obligarte a pegar secretos en la terminal. Si trabajas con un equipo, además, los arreglos de .mcp.json reducen el riesgo de perder configuración ajena al correr comandos de MCP. Si estás empezando con las instrucciones persistentes del proyecto, mira también nuestro ejemplo comentado de CLAUDE.md.

Preguntas frecuentes

¿Puedo usar el guion de stdin dentro de una sesión de Claude Code?

No. El changelog indica que esa forma no está disponible dentro de una sesión de Claude Code; ejecútala desde tu terminal.

¿Sirve para servidores stdio o solo para remotos?

La documentación muestra add-json con ejemplos de servidores remotos y de servidores locales con command y args. Para la forma con stdin el changelog no distingue tipos, pero no la probamos con ninguno.

¿Qué pasa si me equivoco en el JSON?

El changelog de la versión 2.1.326 dice que add-json ya no responde con un error genérico a la mayoría de equivocaciones y ahora indica qué cambiar. Recuerda pasar el objeto interior de mcpServers, no el contenedor completo.

Fuentes

Última revisión: 18 de noviembre de 2026. Este artículo fue preparado con ayuda de IA; consulta cómo usamos la IA. Los comandos provienen de la documentación oficial y del changelog, salvo el ejemplo con stdin que armamos nosotros; no se ejecutaron. Parte de la página de documentación de MCP se leyó mediante resumen automático, así que verifica los detalles en la fuente.