Servidor MCP
Conecta Claude Desktop, Claude Code, Cursor o cualquier cliente compatible con MCP a sh0 y gestiona tus despliegues a través de lenguaje natural.
Qué es MCP
El Model Context Protocol (MCP) es un estándar abierto para conectar asistentes de IA con herramientas y fuentes de datos externas. En vez de copiar y pegar la salida de la terminal en una ventana de chat, MCP permite que tu asistente de IA interactúe con sh0 directamente -- listando apps, leyendo logs, activando despliegues y diagnosticando problemas.
sh0 incluye un servidor MCP integrado expuesto en POST /api/v1/mcp usando el transporte Streamable HTTP. Cualquier cliente que soporte MCP puede conectarse con nada más que una URL y una clave API.
Conectar Claude Desktop
Agrega lo siguiente a tu archivo de configuración de Claude Desktop en ~/.claude/claude_desktop_config.json:
{
"mcpServers": {
"sh0": {
"type": "url",
"url": "https://your-server.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer sh0_your_api_key"
}
}
}
}Reemplaza your-server.com con la dirección de tu servidor sh0 y sh0_your_api_key con una clave API válida. Reinicia Claude Desktop para cargar la nueva configuración.
Conectar Claude Code
Para Claude Code (el CLI), agrega la misma configuración en ~/.claude.json bajo la clave mcpServers:
{
"mcpServers": {
"sh0": {
"type": "url",
"url": "https://your-server.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer sh0_your_api_key"
}
}
}
}Una vez configurado, Claude Code descubrirá y usará automáticamente las herramientas de sh0 cuando sea relevante para tus indicaciones.
Conectar Cursor
En Cursor, abre Settings → MCP y agrega un nuevo servidor con la misma configuración JSON:
{
"mcpServers": {
"sh0": {
"type": "url",
"url": "https://your-server.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer sh0_your_api_key"
}
}
}
}La configuración es idéntica en los tres clientes. Cualquier herramienta compatible con MCP que soporte el transporte Streamable HTTP funcionará con la misma URL y credenciales.
curl -X POST https://your-server/api/v1/mcp -H 'Authorization: Bearer sh0_xxx' -H 'Content-Type: application/json' -d 'undefined,"clientInfo":undefined}}'Alcances de claves API
Las claves API controlan qué herramientas puede acceder el asistente de IA. A cada clave se le asigna un alcance que determina sus permisos:
| Alcance | Herramientas | Descripción |
|---|---|---|
read | Las 45 herramientas de lectura | Listar e inspeccionar apps, servicios, dominios, logs y métricas. Sin modificaciones permitidas. |
deploy | Lectura + despliegue | Todo lo de read, más desplegar, revertir, reiniciar, iniciar, detener y escalar aplicaciones existentes. No puede crear ni eliminar aplicaciones, cambiar su configuración o sus dominios, ejecutar comandos ni crear claves de API. |
admin | Las 106 herramientas | Acceso completo: creación de aplicaciones (create_app, upload_app, deploy_template, deploy_compose), herramientas del sandbox, ajustes del servidor, gestión de usuarios, copias de seguridad y acciones destructivas. Ninguna clave, ni siquiera una admin, puede crear otra clave de API. |
Para crear una clave de API, vaya a Ajustes → Claves API en el panel. Elija el alcance según lo que deba hacer la IA. Para el trabajo diario sobre aplicaciones existentes, deploy ofrece el equilibrio adecuado entre capacidad y seguridad. Las claves creadas antes de la v1.10.2 con el alcance standard se leen como deploy.
admin solo cuando la IA deba crear o eliminar aplicaciones, cambiar la configuración o ejecutar comandos. Para desplegar y reiniciar aplicaciones existentes se recomienda deploy.Autodescubrimiento
Las 106 herramientas son descubiertas automáticamente por los clientes MCP. No se necesita registro manual de herramientas. Cuando un cliente se conecta, llama al método tools/list, y sh0 responde con el catálogo completo de herramientas -- nombres, descripciones y definiciones de parámetros JSON Schema.
La lista es la misma para todas las claves: tools/list devuelve las 106 herramientas (45 de lectura, 45 de escritura, 16 destructivas). El alcance de la clave se comprueba cuando se llama a una herramienta: una clave read que llama a una herramienta de escritura recibe «API key scope 'read' cannot execute 'write' risk tools».
Gestión de sesiones
El servidor MCP usa sesiones para mantener el estado a través de múltiples solicitudes dentro de una conversación. Cada sesión se identifica con un UUID v4 devuelto en el encabezado de respuesta Mcp-Session-Id después de la llamada initialize.
Los clientes deben incluir este encabezado en todas las solicitudes subsiguientes. Detalles de la sesión:
- Formato de ID: UUID v4 (ej.,
a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d) - TTL: 1 hora de inactividad
- Eliminación: Diferida -- las sesiones expiradas se limpian cuando se crean nuevas sesiones
- Alcance: Cada sesión hereda el alcance de la clave API utilizada durante la inicialización
Solución de problemas
Problemas comunes al conectarse al servidor MCP:
Conexión rechazada
Verifica que el servidor sh0 esté funcionando y que el puerto sea accesible. Si te conectas desde fuera de la red local, asegúrate de que tu firewall permita tráfico entrante en el puerto API de sh0 (por defecto 9000).
HTTPS requerido
Los clientes MCP generalmente requieren HTTPS para conexiones remotas. Si accedes a sh0 por internet, asegúrate de que tu servidor tenga un certificado SSL válido. Las conexiones locales a localhost o 127.0.0.1 pueden funcionar con HTTP simple.
Herramientas no aparecen
Si la conexión se establece pero no aparecen herramientas, el alcance de la clave API puede ser demasiado estrecho para las herramientas que esperas. Verifica que la clave tenga el alcance correcto en Settings → API Keys. También verifica que el encabezado Authorization esté formateado correctamente como Bearer sh0_....
Sesión expirada
Las sesiones expiran después de 1 hora de inactividad. Si recibes un error de sesión, el cliente debería reinicializarse automáticamente. Si no lo hace, reinicia el cliente MCP para crear una nueva sesión.