Hace dos semanas, construimos un asistente IA en sh0 que podía consultar tu servidor, reiniciar tus aplicaciones, y generar archivos de configuración. Funcionaba. Pero la arquitectura tenía un problema que sabía que tendríamos que resolver.
El bucle de llamada de herramientas era complejo. Esto es lo que sucedía cada vez que Claude quería verificar el estado de tu servidor:
- Envías un mensaje a la pasarela en
sh0.dev/api/ai/chat - La pasarela llama a Claude con 9 definiciones de herramientas
- Claude responde con un bloque
tool_use: "Quiero llamarget_server_status" - La pasarela emite un evento SSE
tool_callal dashboard - El JavaScript del dashboard captura el evento, llama la API REST local de sh0-core
- El dashboard envía el resultado de vuelta a la pasarela como
tool_results - La pasarela llama a Claude de nuevo con los resultados
- Claude responde con texto
- Los pasos 3-8 se repiten para cada llamada de herramienta en la conversación
Nueve pasos. Tres viajes ida y vuelta de red. Definiciones de herramientas duplicadas en dos archivos -- uno en la pasarela, uno en el dashboard. El dashboard tenía una función recursiva runStreamLoop que gestionaba todo el bucle agéntico del lado del cliente. Funcionaba, pero era el tipo de arquitectura que te pone nervioso cuando piensas en los casos extremos.
El protocolo que ya existía
Mientras construíamos esto, sh0-core ya tenía un servidor MCP completo. Veinte herramientas, JSON-RPC 2.0 adecuado, transporte HTTP streamable, alcance de claves API, tokens de confirmación para operaciones destructivas. Lo construimos a lo largo de tres fases, lo auditamos dos veces por fase. Estaba listo para producción.
Y la API de Claude tenía algo llamado MCP Connector -- una funcionalidad beta que te permite decirle a Claude "aquí hay un servidor MCP, conéctate tú mismo."
La solución era obvia. En lugar de que la pasarela defina herramientas y el dashboard las ejecute, simplemente dile a Claude dónde está el servidor MCP. Deja que Claude maneje el descubrimiento y la ejecución de herramientas directamente. Todo el bucle del lado del cliente desaparece.
Cómo se ve el código
La forma anterior:
typescriptconst response = await client.messages.create({
model: modelString,
max_tokens: 4096,
system: systemPrompt,
messages: apiMessages,
tools: SH0_TOOLS, // 9 definiciones de herramientas, mantenidas manualmente
stream: true,
});
// Luego: parsear bloques tool_use, emitir eventos SSE, esperar a que el dashboard
// ejecute, recibir resultados, llamar a Claude de nuevo...La forma nueva:
typescriptconst response = await client.beta.messages.create({
model: modelString,
max_tokens: 4096,
system: systemPrompt,
messages: apiMessages,
mcp_servers: [{
type: 'url',
url: `${instanceConfig.instanceUrl}/api/v1/mcp`,
name: 'sh0',
authorization_token: decryptedInstanceKey,
}],
tools: [
{ type: 'mcp_toolset', mcp_server_name: 'sh0' },
...GATEWAY_ONLY_TOOLS,
],
betas: ['mcp-client-2025-11-20'],
stream: true,
});
// Listo. Claude descubre herramientas vía MCP, las llama directamente.
// El stream contiene bloques mcp_tool_use/result informativos.Claude se conecta al servidor MCP, descubre las 20 herramientas vía tools/list, y las llama directamente. El stream de respuesta incluye bloques de contenido mcp_tool_use y mcp_tool_result que reenviamos al dashboard solo para fines de visualización. Sin ejecución. Sin viajes ida y vuelta. Sin bucle recursivo.
El dashboard muestra pasos de procesamiento -- "Verificando estado del servidor", "Listando aplicaciones" -- pero es puramente cosmético. El trabajo real sucede entre Claude y el servidor MCP, dos máquinas hablando entre sí mientras el usuario ve el texto transmitirse.
Las decisiones que importaron
Las herramientas manejadas por la pasarela se mantienen como herramientas regulares
No todo es una herramienta MCP. suggest_actions genera chips de acciones de seguimiento. generate_config_file crea tarjetas de configuración descargables. Estas son funcionalidades de UI manejadas por la propia pasarela -- no tocan el servidor sh0-core.
Mantenemos estas como definiciones regulares de herramientas Anthropic junto al toolset MCP. Cuando Claude las llama, la pasarela las procesa y emite los eventos SSE apropiados. Esto requiere un bucle interno -- Claude se detiene con stop_reason: 'tool_use', proporcionamos los resultados de la herramienta, Claude continúa. Como máximo un viaje ida y vuelta extra, y solo cuando Claude sugiere acciones de seguimiento.
La ruta heredada se mantiene
MCP Connector solo funciona cuando la instancia de sh0 es accesible vía HTTPS desde los servidores de Anthropic. Si estás ejecutando sh0 en una máquina local, detrás de un firewall, o en una red que Claude no puede alcanzar, la ruta MCP falla.
Cuando falla, la pasarela emite un evento SSE mcp_fallback con la razón, resetea su estado, y ejecuta toda la solicitud a través de la ruta heredada de llamada de herramientas. El dashboard maneja ambos modos transparentemente -- si llegan eventos mcp_tool_use, los muestra como pasos de procesamiento; si en cambio llegan eventos tool_call, el bucle agéntico recursivo entra en acción como antes.
Sin fallos silenciosos. El usuario sabe qué pasó y aún obtiene una respuesta funcional.
La contabilidad de tokens no cambia
La respuesta del MCP Connector incluye el uso total de tokens igual que una respuesta regular. message_start tiene input_tokens, message_delta tiene output_tokens. La sobrecarga de llamadas de herramientas MCP -- los tokens que Claude usa para formatear solicitudes y parsear respuestas del servidor MCP -- se incluye en estos conteos automáticamente. La lógica de deducción del monedero no cambió en absoluto.
Lo que entregamos
La implementación toca ambos código base:
sh0-website (pasarela):
- Nuevo modelo Prisma para configuración de instancia (almacenamiento encriptado de claves API)
- Nueva ruta API para gestionar configuración de instancia
- Endpoint de chat dividido en streamMcpPath() y streamLegacyPath()
- Variante de prompt del sistema para modo MCP
- Definiciones de herramientas divididas: herramientas de cliente, herramientas de pasarela, combinadas
Dashboard de sh0-core: - Tres nuevos manejadores de eventos SSE (solo informativos) - Etiquetas e íconos de herramientas MCP para las 20 herramientas del servidor - Corrección de error: bloques tool_result ahora se rastrean correctamente en historial de conversación
El código del bucle agéntico del dashboard no fue eliminado. Ni una sola línea. Simplemente nunca se ejecuta cuando MCP está activo porque los eventos que lo disparan nunca se emiten. Este es el tipo de simplificación que encuentro más satisfactorio -- no eliminar código, sino hacerlo irrelevante a través de una mejor abstracción.
La lección arquitectónica
La arquitectura anterior tenía la separación correcta de responsabilidades pero el modelo de ejecución equivocado. La pasarela sabía sobre herramientas. El dashboard ejecutaba herramientas. Claude orquestaba. Cada capa hacía su trabajo, pero la coreografía entre ellas era frágil.
El MCP Connector colapsa el modelo de ejecución. Claude y el servidor MCP manejan todo el ciclo de vida de herramientas. La pasarela se convierte en un pass-through. El dashboard se convierte en un display. La complejidad no desaparece -- se mueve a un límite de protocolo donde pertenece.
Para eso es el diseño de protocolos. No para hacer las cosas más simples en teoría, sino para mover la complejidad a donde puede ser gestionada por máquinas en lugar de mantenida por ingenieros.
Veinte herramientas. Cero ejecución del lado del cliente. Un protocolo.