Despliega y depura proyectos de Zenavo desde Claude Code

Cuando terminas un cambio y quieres subirlo a producción —o cuando un servicio falla al arrancar—, lo habitual es ir saltando entre la terminal y el navegador: buscar el proyecto, pulsar desplegar, esperar a que compile y revisar los registros.

Al conectar el MCP y los Skills de Zenavo a Claude Code, todo eso se hace desde la misma conversación en la terminal. Puedes pedirle directamente: «Mira por qué ha fallado el último despliegue del servicio web, saca las líneas del error en los registros y dime cómo arreglarlo».

Si prefieres preguntar directamente en el navegador sin instalar nada en local, haz clic en Zenavo Agent en el borde derecho de cualquier página de la consola: detecta qué página tienes abierta, lee los registros y despliegues y te propone cambios (desplegar, revertir, reiniciar o configurar variables) mediante tarjetas de confirmación en la propia página. En esta guía vemos cómo llevar esas mismas capacidades a Claude Code en tu ordenador.

1. Instala e inicia sesión en zenavo-mcp

Descarga el binario para tu sistema desde zenavo-mcp Releases, déjalo en tu PATH y ejecuta en la terminal:

zenavo-mcp login

Se abrirá en el navegador la página de autorización del dispositivo. Comprueba que el código coincide con el de la terminal y elige el nivel de permisos:

• Solo lectura (Read-only): permite ver proyectos, estado de los servicios, historial de despliegues, registros y nombres de variables de entorno (nunca sus valores en texto plano), ideal para depurar en el día a día;
• Despliegue (Deploy): añade permiso para lanzar despliegues, reiniciar servicios, revertir a una versión anterior y modificar variables de entorno.

En el alcance de proyectos, elige Solo proyectos seleccionados y marca únicamente los proyectos en los que estés trabajando. Una vez autorizado, el token se guarda en tu equipo y no tienes que pegar ninguna clave de API en el chat.

A continuación, instala el plugin de Zenavo en Claude Code (que configura el servidor MCP e incluye los Skills de despliegue, depuración, reversión y variables):

claude plugin marketplace add Zenavo-App/zenavo-skills
claude plugin install zenavo@zenavo

Si solo quieres la conexión MCP sin el plugin, puedes ejecutar claude mcp add zenavo -- zenavo-mcp. Las instrucciones para Cursor, Windsurf y otros editores están en la documentación de agentes de IA y en la página de Skills.

2. Consulta el estado del proyecto y los últimos despliegues

Empieza con una petición de solo lectura para confirmar que ve tu proyecto:

Revisa mi proyecto en Zenavo y muéstrame el estado de cada servicio y el resultado del último despliegue.

Claude Code consultará el MCP y listará los servicios, su estado actual (Running, Crashed, etc.) y las últimas tareas de compilación y despliegue.

Por diseño de seguridad, el MCP nunca devuelve el valor en texto plano de las variables de entorno (solo sus nombres), y tampoco puede leer filas de la base de datos ni descargar copias de seguridad. Así, aunque compartas contexto con el modelo mientras depuras, tus claves y los datos de tus clientes no pasan por el chat.

3. Localiza fallos de compilación o arranque con los registros

Cuando falle un despliegue o un contenedor se reinicie en bucle, pídele que revise los registros por etapas en lugar de buscar línea por línea:

Revisa el último despliegue fallido del servicio web.
Mira los registros para ver si ha fallado al instalar dependencias, al compilar, al arrancar el contenedor o en la comprobación de salud; muéstrame el error exacto y cómo corregirlo.

Una vez localizada la causa:

• Error de dependencias o compilación: deja que Claude Code corrija el código en local, compruebe que compila, haga commit y lo suba a GitHub;
• Falta una variable de entorno: pídele que la añada (tras tu confirmación) y reinicie el servicio;
• Puerto o comprobación de salud incorrectos: verifica que la aplicación escucha en 0.0.0.0 y en el mismo puerto HTTP configurado en el servicio.

4. Lanza un despliegue y comprueba el arranque

Cuando quieras publicar una versión nueva:

Despliega el servicio web de mi proyecto de pruebas, sigue la compilación y el despliegue hasta que termine y revisa los registros de arranque por si hay errores.

Recuerda: Zenavo despliega la rama remota de Git o la imagen Docker configurada en el servicio. Si has hecho cambios en tu ordenador pero aún no has hecho git push, súbelos primero al repositorio antes de pedirle que despliegue.

Cualquier acción que modifique el servicio (desplegar, reiniciar, cambiar variables o revertir) te mostrará antes los parámetros y te pedirá confirmación.

5. Revierte rápido si una versión nueva falla

Si acabas de desplegar una versión con algún problema, puedes pedirle que vuelva a la versión anterior:

Mira el historial de despliegues de web, busca la última versión que funcionó, revierte a ella y confirma que el servicio vuelve a estar sano.

Un detalle importante antes de revertir: revertir un servicio restaura la imagen y las variables de entorno de aquel despliegue, pero no deshace cambios en la base de datos ni en los volúmenes (ver Revertir un despliegue). Si la versión nueva aplicó una migración de base de datos incompatible hacia atrás, comprueba primero que el código anterior puede funcionar con el esquema actual.

6. Registro de auditoría y revocación de permisos

Cada despliegue, reinicio, reversión o cambio de variables hecho a través de MCP queda anotado en el registro de auditoría de la consola.

Las claves creadas con zenavo-mcp login aparecen en Cuenta → Claves de API con el nombre MCP on <nombre-del-equipo> y caducan a los 90 días. Si cambias de ordenador o ya no necesitas la conexión, bórrala ahí mismo para revocar el acceso al instante.

Preguntas frecuentes

¿Puede comprar servidores, borrar proyectos o leer las tablas de mi base de datos? No. El MCP de Zenavo excluye deliberadamente operaciones delicadas como comprar o destruir servidores, borrar proyectos, tocar la facturación, abrir una terminal en el contenedor, consultar filas de bases de datos o descargar copias de seguridad. Esas acciones solo se hacen desde la consola.

¿He instalado el plugin pero dice que no ve ningún proyecto? Comprueba que has ejecutado zenavo-mcp login en la terminal y que marcaste ese proyecto al autorizar el dispositivo. Para autorizar proyectos adicionales, vuelve a ejecutar zenavo-mcp login.

¿Cuándo conviene usar solo lectura y cuándo permisos de despliegue? Para producción es buena idea usar solo lectura en el día a día, de modo que Claude Code te ayude a analizar registros y preparar el arreglo en el código; en proyectos de desarrollo o pruebas puedes darle permiso de despliegue para que complete de principio a fin el ciclo de «corregir → subir a Git → desplegar → verificar registros».

¿Qué diferencia hay entre el Zenavo Agent integrado en la consola y Claude Code con MCP? Zenavo Agent está integrado en la consola web (incluido en los planes Dev, Pro y Team con 30, 100 y 300 créditos al mes): basta con abrir la página de un servicio, preguntar por qué falla y confirmar el cambio propuesto en una tarjeta. Claude Code + zenavo-mcp corre en tu terminal local junto a tu código fuente, por lo que resulta ideal para leer los registros, editar el código en local, hacer push a GitHub y volver a desplegar de una sola vez. Y si quieres que Claude Code cambie de modelo o comparta cuotas de API en equipo, puedes combinarlo con una pasarela Magpie o New API autoalojada en Zenavo, y conectar esa misma pasarela a Open WebUI o LobeHub para chatear desde el navegador.

Pruébalo primero en un proyecto de prueba: ejecuta zenavo-mcp login, instala el plugin zenavo@zenavo y deja que Claude Code revise un registro o publique un despliegue.