Phantom Secrets: un proxy local y un servidor MCP que ocultan los secretos reales a los agentes de codificación con IA

Para quién es

Si has integrado un agente de codificación con IA en tu desarrollo del día a día y el .env de tu proyecto guarda secretos reales, los registros, los ecos de error y los fragmentos de contexto pueden convertirse todos en vías de fuga. Phantom va dirigido a quien necesita una frontera clara entre «la aplicación sigue recibiendo los valores reales» y «el agente nunca ve el valor del secreto», así como a los equipos que quieren distribuir y rotar secretos de forma centralizada sin desplegarlos en la cadena de herramientas de cada persona.

Su forma es «proxy local + servidor MCP»: los secretos del proyecto se sustituyen por marcadores phm_ con ámbito, la aplicación obtiene los valores reales a través de un proxy local autenticado y el lado del agente solo accede a herramientas MCP ciegas a los valores, destinadas al inventario, el diagnóstico y las peticiones controladas. La premisa es que quieras mantener un proceso proxy siempre en marcha en tu máquina y meter la reescritura del .env en tu propio proceso de control de versiones: ese paso no se puede omitir a la ligera.

Tres minutos para el primer intento

La vía oficial recomendada es Homebrew. La instalación en macOS que indica el repositorio es una cadena de tres pasos: primero tap, luego trust y por último install; el resultado son dos ejecutables, phantom y phantom-mcp, correspondientes a la versión v0.7.9 que señala el repositorio.

brew tap ashlrai/phantom
brew trust --formula ashlrai/phantom/phantom
brew install ashlrai/phantom/phantom

Requisitos previos: Homebrew ya debe estar instalado en macOS; si no usas Homebrew y compilas el código fuente por tu cuenta, el repositorio fija la versión de la cadena de herramientas de compilación, así que tu entorno de compilación necesita la cadena de herramientas de Rust de esa versión.

A continuación vienen dos pasos de configuración, en orden. Primero entra en el directorio del proyecto y ejecuta phantom init; ten en cuenta que es una operación de escritura: reescribe el .env de ese proyecto y cambia los valores reales de las claves por marcadores phm_; el punto de control es confirmar antes de ejecutar que el .env está respaldado o versionado, y comprobar en la salida del comando que el número de sustituciones coincide con lo esperado. El segundo paso escribe la configuración para el cliente correspondiente:

phantom init
phantom setup --client claude

Después, usa el paso de solo lectura para una verificación de bajo riesgo: phantom list enumera tu inventario de secretos sin mostrar ningún valor. La señal de éxito observable es que la terminal lista los nombres de las entradas y que detrás de ninguna aparece un carácter de secreto real; luego pide al agente que vuelva a leer el repositorio y lo que obtiene son cosas que empiezan por phm_ en lugar de los valores reales.

Para la referencia completa de comandos y opciones, consulta el repositorio oficial https://github.com/ashlrai/phantom-secrets

Casos de uso

Caso uno: dar al agente un canal donde ve el inventario pero no los valores. Las herramientas MCP del lado del agente son ciegas a los valores y cubren tres usos: inventario, diagnóstico y peticiones controladas; el repositorio sitúa esas herramientas como comprobaciones de capacidad, de estado y de estado del repositorio, que no disparan ninguna acción en el lado del proveedor. Así puedes preguntar con confianza al agente «qué secretos tiene configurados este proyecto, si la ruta actual funciona y qué archivos del repositorio referencian marcadores»: el agente no devuelve los valores de los secretos ni cambia de paso los recursos en la nube durante la comprobación.

Caso dos: que el código de negocio siga ejecutándose con los valores reales mientras esos valores quedan fuera de la vista del agente. La sustitución ocurre en la fase de inicialización: los valores reales de las claves del .env se convierten en marcadores phm_ con ámbito, la aplicación sigue leyendo las variables de entorno como de costumbre y las peticiones que lanza las asume el proxy local, que recupera los valores reales tras la autenticación. El punto de entrada de peticiones controladas del lado del proxy comparte la misma restricción «sin valores» que los puntos de entrada de inventario y de diagnóstico, así que la aplicación funciona y el agente sigue sin poder conseguir los secretos en sí. Conviene tener en cuenta que la documentación del repositorio solo dice que el proxy es un proxy local «autenticado» y no detalla la forma concreta de esa autenticación; en esa capa, átente al repositorio.

Límites de uso

Primero: phantom init reescribe el .env, es una operación de escritura de verdad. Haz una copia de seguridad o confirma antes de ejecutarlo, y no pegues el diff previo y posterior directamente en un canal público.

Segundo: la condición de ceguera a los valores de las herramientas del lado del agente solo garantiza «no ver valores», no «poder hacerlo todo». El repositorio las sitúa como comprobaciones de capacidad, de estado y de estado del repositorio y no lanza por ti acciones de proveedor; las llamadas reales a la nube ocurren en la ruta de petición que la aplicación envía a través del proxy local, así que al investigar hay que distinguir esos dos tramos.

Tercero: no es una herramienta sin riesgo: tiene que leer el .env local y los archivos de configuración del cliente, y el proxy local envía peticiones a proveedores de terceros, de modo que los secretos siguen circulando entre tu máquina y ese proveedor. Si aceptas o no ese camino depende de si tu organización permite que exista en el lado del agente.

Cuarto: los métodos de instalación y las descripciones de comandos del repositorio cambian con las versiones, así que antes de actualizar vuelve a comprobarlos en el repositorio oficial.