{*}SecureCodeHQ
Cómo gestionar secretos de forma segura con Claude Code
·por Juan Isidoro·8 min de lectura

Cómo gestionar secretos de forma segura con Claude Code

Guía práctica para mantener tus API keys, tokens y contraseñas fuera de la ventana de contexto de Claude Code usando el enfoque zero-knowledge inject.

claude-codesecretsmcptutorial

El informe "State of Secrets Sprawl 2026" de GitGuardian, publicado el 17 de marzo de 2026, detectó 28.65 millones de secretos expuestos en repositorios públicos. Los commits asistidos por IA tienen una tasa de filtración del 3.2%, el doble que los commits escritos solo por humanos. Si usas Claude Code a diario, tus archivos .env están más expuestos de lo que crees.

Un estudio aparte encontró 24,008 secretos hardcodeados en archivos de configuración .mcp.json en repositorios públicos de GitHub. Los desarrolladores no solo filtran secretos de aplicaciones, sino también las claves que conectan sus herramientas de IA con servicios externos.

Esta guía te enseña a usar secretos en Claude Code sin que la IA llegue a verlos.

Por qué los archivos .env son peligrosos con asistentes de IA

Cuando Claude Code se ejecuta en tu proyecto, puede leer cualquier archivo del directorio de trabajo. Eso incluye .env, .env.local y cualquier otro archivo donde guardes API keys. En cuanto Claude lee tu .env para "ayudarte a configurar la conexión a la base de datos", tu clave de Stripe, tu contraseña de base de datos y tus credenciales de AWS quedan dentro del contexto de la conversación.

A partir de ahí, los secretos pueden acabar en:

  • El historial del chat almacenado en los servidores de Anthropic (retención de 30 días por defecto)
  • Mensajes de commit o sugerencias de código que incluyen el valor real
  • La salida del terminal visible en la conversación
  • Los logs si Claude ejecuta comandos que imprimen variables de entorno

Para un análisis más detallado, lee Por qué los archivos .env son peligrosos con agentes IA.

Qué significa Zero-Knowledge Inject

La idea central: nunca dejar que la IA vea el valor del secreto. En lugar de devolver sk_live_abc123 a la conversación, se escribe en un archivo temporal y se le indica a Claude solo la ruta.

Le pides a Claude que haga deploy con STRIPE_KEY
  1. El servidor MCP obtiene el valor cifrado del vault
  2. Lo descifra en el servidor local
  3. Lo escribe en ~/.securecode/.session/a1b2c3.env
  4. Devuelve a Claude: "STRIPE_KEY injected -> /home/tu/.securecode/.session/a1b2c3.env"
  5. Claude ejecuta: source /home/tu/.securecode/.session/a1b2c3.env && npm run deploy

El valor nunca entra en la ventana de contexto. El historial del chat muestra solo la ruta del archivo. Claude sabe que el secreto existe pero no puede leer su contenido.

+------------------+       +------------------+       +------------------+
|   Claude Code    |       |  SecureCode MCP  |       |   SecureCode     |
|   (tu editor)    |       |  (servidor local)|       |   Vault (cloud)  |
+--------+---------+       +--------+---------+       +--------+---------+
         |                          |                          |
         | 1. get-secret            |                          |
         |   name: STRIPE_KEY       |                          |
         |------------------------->|                          |
         |                          | 2. Obtener + descifrar   |
         |                          |------------------------->|
         |                          |<-------------------------|
         |                          |                          |
         |                          | 3. Escribir en archivo   |
         |                          |   (permisos 0600)        |
         |                          |                          |
         | 4. "STRIPE_KEY injected  |                          |
         |    -> /ruta/al/archivo"  |                          |
         |<-------------------------|                          |
         |                          |                          |
         | 5. source /ruta && deploy|                          |
         |                          |                          |

Configurar SecureCode MCP

SecureCode es un vault de secretos diseñado para este flujo de trabajo. Se conecta a Claude Code por MCP (Model Context Protocol) y gestiona la inyección de forma automática.

Paso 1: Instalar el servidor MCP

Agrega SecureCode a la configuración MCP de Claude Code. Crea o edita .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "securecode": {
      "command": "npx",
      "args": ["-y", "@securecode/mcp-server"],
      "env": {
        "SECURECODE_API_KEY": "${SECURECODE_API_KEY}"
      }
    }
  }
}

La sintaxis ${SECURECODE_API_KEY} le indica a Claude Code que expanda la variable desde tu entorno. El valor real de la clave nunca aparece en el archivo de configuración.

Paso 2: Ejecutar el onboarding

Abre Claude Code en tu proyecto y escribe:

"Set up SecureCode"

El MCP te guía para crear una cuenta, importar tu archivo .env desde el panel web (para que Claude nunca vea los valores) y generar una API key. La clave se guarda en .securecoderc, que se agrega automáticamente a .gitignore.

Paso 3: Usar secretos

Una vez configurado, pídele a Claude que use cualquier secreto:

"Deploy this to production using the DATABASE_URL"

Claude llama a get-secret a través del MCP. El valor se inyecta en un archivo local. Claude ejecuta tu comando con source /ruta && deploy-command. Listo.

Cómo funciona el modo inject por dentro

El servidor MCP crea un directorio de sesión en ~/.securecode/.session/ con permisos 0700 (solo el propietario). Cada sesión obtiene un archivo con un nombre generado a partir de un hash de apiKey + PID, así que las sesiones paralelas de Claude Code nunca colisionan.

El archivo del secreto se escribe con permisos 0600 (solo lectura y escritura del propietario). Los valores con comillas simples se escapan correctamente para prevenir inyección de shell. Cada nueva inyección sobreescribe el archivo anterior, manteniendo la ventana de exposición al mínimo.

Cuando terminas de trabajar, el comando byebye bloquea la sesión y elimina todos los archivos inyectados del disco. Ningún valor de secreto queda en el sistema de archivos.

Tips de bloqueo que te protegen

La primera vez que accedes a un secreto en una sesión, SecureCode devuelve un tip de bloqueo en lugar del valor. Claude tiene que confirmar el tip y llamar a get-secret de nuevo. Esto fuerza una pausa donde ves:

"Welcome to SecureCodeHQ! Remember: secret values returned here are injected directly into your workflow. Never paste them in chat messages, commit them to git, or include them in code files."

También hay un aviso de bloqueo cuando accedes a un secreto etiquetado como producción:

"Warning: You are accessing DATABASE_URL which is tagged as PRODUCTION. Make sure this is intentional."

Estos tips solo se muestran una vez por sesión (máximo 3 en total), así que no resultan molestos.

Agregar el SDK para acceso en runtime

Para que tu aplicación lea secretos en tiempo de ejecución (sin pasar por Claude), instala el SDK:

npm install @securecode/sdk

Agrega una línea al punto de entrada de tu aplicación:

import { loadEnv } from "@securecode/sdk";
await loadEnv({ override: true });

Después de esto, process.env.DATABASE_URL, process.env.STRIPE_KEY y cualquier otro secreto funcionan con normalidad. No hace falta cambiar nada más en tu código.

El SDK lee la API key desde .securecoderc (creado durante el onboarding, agregado a .gitignore automáticamente). Para producción, configura SECURECODE_API_KEY como variable de entorno en tu plataforma de hosting.

Checklist de seguridad

Después de la configuración, ejecuta security-check desde el MCP para verificar que todo está protegido:

  • .securecoderc existe y está en .gitignore
  • .mcp.json está en .gitignore (si contiene API keys directamente)
  • .securecoderc está listado en permissions.deny en la configuración de Claude Code
  • .env y .env.* están listados en permissions.deny
  • CLAUDE.md instruye a Claude a usar MCP para secretos

La configuración permissions.deny en el settings.json de Claude Code impide que Claude lea archivos específicos. Este es el mecanismo correcto para bloquear el acceso a archivos. Nota: .claudeignore no es una funcionalidad oficial de Claude Code. Usa permissions.deny en su lugar.

Ejemplo de settings.json:

{
  "permissions": {
    "deny": [
      "Read(.securecoderc)",
      "Read(.env)",
      "Read(.env.*)"
    ]
  }
}

El sistema de permisos usa tres niveles de prioridad: deny (el más alto), ask y allow (el más bajo). Todo lo que esté en deny se bloquea sin importar las demás configuraciones.

El MCP ejecuta esta comprobación automáticamente después de configurar el SDK y corrige los problemas que encuentre.

Seguridad integrada de Claude Code

Claude Code incluye mecanismos de seguridad que vale la pena conocer:

Sistema de permisos. Cada acción potencialmente peligrosa (escritura de archivos, comandos bash, llamadas a herramientas MCP) pasa por el sistema de permisos. Los tres modos son deny, ask y allow, evaluados en ese orden de prioridad. Puedes bloquear operaciones sensibles para que Claude no las ejecute sin tu aprobación.

Sandbox. Claude Code ejecuta los comandos bash dentro de un sandbox restringido. En Linux usa bubblewrap. En macOS usa seatbelt. Esto limita a qué pueden acceder los procesos, reduciendo el impacto si un comando intenta leer archivos fuera del proyecto.

CVE-2025-55284. En 2025, investigadores de Knostic reportaron una vulnerabilidad de exfiltración DNS en la herramienta bash de Claude Code. Fue parcheada, pero es un recordatorio de que el sandboxing y los controles de permisos importan. La defensa en profundidad es la razón por la que quieres los secretos fuera de la ventana de contexto por completo, no solo protegidos detrás de permisos de archivo.

Qué pasa con tus datos

Anthropic retiene los datos de conversación durante 30 días por defecto. Si aceptas compartir datos para entrenamiento, la retención se extiende a 5 años. Puedes desactivar esto desde la configuración de tu cuenta de Anthropic.

Justamente por esto importa el zero-knowledge inject: si el valor del secreto nunca entra en la conversación, no forma parte de los datos que Anthropic retiene. El historial del chat solo muestra "STRIPE_KEY injected" con una ruta de archivo, no la clave real.

Modo Reveal para depuración

A veces necesitas que Claude vea el valor, por ejemplo cuando estás depurando un problema de autenticación. Puedes usar reveal: true al llamar a get-secret. Esto devuelve el valor sin cifrar a la conversación, pero queda registrado como una acción consciente en el audit trail. Tu equipo puede revisar quién reveló qué y cuándo.

Usa esto con moderación. Cada reveal pone el valor del secreto en el contexto de la conversación y, por extensión, en la ventana de retención de 30 días de Anthropic.

Lectura adicional