Docs/ Asistente de IA/ Servidor MCP

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 /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:

~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/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:

~/.claude.json

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/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:

Cursor MCP Settings

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/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.

Tip

Puedes probar tu conexión MCP con:

curl -X POST https://your-server/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`	37 herramientas	Listar e inspeccionar apps, servicios, dominios, logs y métricas. Sin modificaciones permitidas.
`standard`	Read + write	Todo lo de read, más crear apps, activar despliegues, actualizar variables de entorno y gestionar dominios.
`admin`	Las 103 herramientas	Acceso completo incluyendo configuración del servidor, gestión de usuarios, operaciones de respaldo y acciones destructivas.

Para crear una clave API, navega a Settings → API Keys en el panel de control. Elige el alcance apropiado según lo que necesites que haga la IA. Para la mayoría de flujos de desarrollo, standard proporciona el equilibrio adecuado entre capacidad y seguridad.

Warning

Usa el alcance admin solo cuando la IA necesite realizar operaciones a nivel de servidor. Para el desarrollo diario, se recomienda standard.

Autodescubrimiento

Las 103 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 de herramientas se filtra según el alcance de la clave API. Una clave con alcance read solo verá las 37 herramientas de solo lectura, mientras que una clave admin ve las 103.

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.

Getting Started

AI Sandbox