El AI gateway que construimos en el artículo anterior le daba a Claude 10 herramientas para consultar el servidor de un usuario a través del dashboard. Funcionaba. Pero tenía una limitación fundamental: las herramientas solo existían dentro de nuestra interfaz de chat. Si querías usar Claude Desktop, Cursor o Claude Code para gestionar tu servidor sh0, no podías.
El Model Context Protocol cambió eso. MCP es un estándar abierto -- JSON-RPC 2.0 sobre HTTP -- que permite a cualquier cliente de IA descubrir y llamar herramientas en cualquier servidor. El 24 y 25 de marzo de 2026, construimos un servidor MCP directamente en el binario Rust de sh0. Al final, teníamos 25 herramientas, un sistema de seguridad de tres niveles, generación de herramientas impulsada por OpenAPI y un contenedor sandbox que da a Claude acceso root para depurar tus aplicaciones.
Hicimos esto a lo largo de cinco fases, seis agentes de implementación, diez sesiones de auditoría y aproximadamente diecisiete sesiones totales de Claude orquestadas por el CTO de IA.
Fase 1: La base del protocolo (12 herramientas de solo lectura)
Un servidor MCP necesita tres cosas: una capa de transporte, una capa de protocolo y herramientas. Comenzamos con el transporte.
Transporte HTTP Streamable
La especificación MCP 2025-03-26 define HTTP Streamable como el transporte principal. El cliente envía solicitudes JSON-RPC como HTTP POST a un solo endpoint; el servidor responde con resultados JSON-RPC. El estado de sesión se mantiene vía una cabecera Mcp-Session-Id. Las sesiones expiran después de una hora con desalojo perezoso.
12 herramientas curadas a mano
La Fase 1 definió 12 herramientas de solo lectura: list_apps, get_app_details, get_app_env_vars (solo conteo, nunca valores), list_deployments, get_deployment_logs, list_domains, list_databases, list_cron_jobs, list_backups, list_alerts, get_app_logs y get_server_status.
Críticamente, los valores de variables de entorno nunca se exponen -- solo el conteo. La auditoría detectó dos bugs críticos: métricas obsoletas devueltas (.last() en lugar de .first()) y falta de validación de versión del protocolo.
Fase 2: Generación de herramientas impulsada por OpenAPI
Doce herramientas curadas a mano funcionaban, pero el patrón era frágil. La idea: sh0 ya tiene una especificación OpenAPI generada por utoipa. ¿Por qué escribir definiciones de herramientas dos veces?
El protocolo de extensión x-mcp
Definimos cinco extensiones OpenAPI personalizadas que anotan handlers existentes:
rust#[utoipa::path(
get, path = "/api/v1/apps",
extensions(
("x-mcp-enabled", json!(true)),
("x-mcp-risk", json!("read")),
("x-mcp-description", json!("List all deployed applications with status, domains, and resource usage."))
)
)]Elegimos un enfoque híbrido: las definiciones se auto-generan desde OpenAPI, pero la ejecución permanece manual en tools.rs. Añadir una nueva herramienta MCP requiere dos pasos: (1) añadir extensions(...) a la anotación utoipa del handler, y (2) añadir un brazo match en el ejecutor.
Fase 3: Operaciones de escritura y el sistema de seguridad de tres niveles
Claves API con alcance
Tres niveles de alcance controlan lo que un cliente MCP puede hacer:
| Alcance | Herramientas permitidas |
|---|---|
read | Herramientas de solo lectura (list_apps, get_server_status, etc.) |
standard | Lectura + escritura (restart_app, deploy_app, scale_app, etc.) |
admin | Todas, incluyendo destructivas (delete_app, delete_database) |
Tokens de confirmación para operaciones destructivas
Incluso con alcance admin, las herramientas destructivas no se ejecutan inmediatamente. En su lugar, devuelven un token de confirmación:
json{
"confirmation_required": true,
"confirmation_token": "cf_a1b2c3d4...",
"message": "Esto eliminará permanentemente la aplicación 'my-api' y todos sus datos. Llame a confirm_action con este token para proceder.",
"expires_in_seconds": 300
}El token es de un solo uso, limitado por usuario y expira después de 5 minutos. Esto crea un punto de control humano-en-el-bucle.
Registro de auditoría
Cada llamada de herramienta MCP de escritura y destructiva se registra vía el sistema de auditoría existente, de modo que el panel de administración muestra un historial completo de lo que los clientes de IA han hecho al servidor.
Fase 4: Conector MCP del gateway (enrutamiento de 3 vías)
El conector auto-descubre el endpoint MCP sondeando https://{panel_domain}/api/v1/mcp durante la primera llamada a herramienta. Si responde a una solicitud initialize, el gateway mantiene una sesión MCP y enruta todas las llamadas subsiguientes a través de ella. Si no, recurre al flujo heredado basado en SSE.
La orquestación del CTO: 17 sesiones
El despliegue de MCP fue la orquestación más compleja que había realizado el CTO de IA. Los números cuentan la historia:
- 6 agentes de implementación
- 10 agentes auditores -- dos rondas de auditoría independientes por fase
- 3 bugs críticos detectados en todas las auditorías
- 11 problemas importantes detectados
El conteo final de herramientas
Después de cinco fases, el servidor MCP de sh0 expone 25 herramientas en las categorías: Apps (8), Despliegues (2), Dominios (1), Bases de datos (2), Cron (2), Respaldos (2), Monitoreo (2), Seguridad (1), Sandbox (5).
Cada herramienta tiene una clasificación de riesgo. Cada herramienta de escritura se registra en auditoría. Cada herramienta destructiva requiere confirmación. Cada definición de herramienta se genera desde la especificación OpenAPI (excepto las 6 herramientas manuales que no tienen equivalente REST).
Lo que aprendimos
- La generación impulsada por OpenAPI elimina la divergencia. Una fuente de verdad, dos consumidores.
- La seguridad de tres niveles es el mínimo para operaciones de escritura de IA. Claves con alcance, clasificación de riesgo y tokens de confirmación no son paranoia -- son el mínimo indispensable.
- Las auditorías detectan lo que la implementación no ve. El proceso de auditoría de dos rondas encontró problemas que el agente de implementación no podía ver.
- La orquestación del CTO escala. Diecisiete sesiones en dos días, coordinadas por una sola sesión del CTO de IA, produjeron 25 herramientas con cero regresiones.
Siguiente en la serie: AI Sandbox: dándole a Claude un contenedor seguro para depurar tus aplicaciones -- cómo le dimos a Claude acceso root a un contenedor Alpine para que pueda realmente depurar tus despliegues en vez de adivinar.