MCP outputSchema y structuredContent: contratos de salida para agentes que sí se pueden validar

MCP ya no debería tratar los resultados de tools como texto libre. outputSchema y structuredContent permiten contratos validables, menos parsing frágil y mejores guardrails para agentes.

La actualización 2025-06-18 de Model Context Protocol añadió una pieza menos vistosa que OAuth, pero muy práctica para equipos que construyen agentes: `outputSchema` y `structuredContent` para resultados de herramientas. En vez de devolver solo texto que luego el modelo debe interpretar, un servidor MCP puede declarar qué forma tendrá la salida y devolver JSON validable.

El cambio convierte muchas integraciones MCP en APIs de verdad. La descripción de la tool sigue ayudando al modelo a decidir cuándo usarla; el schema ayuda al runtime a comprobar si el resultado sirve.

Por qué no basta con buen prompting

Un prompt puede pedir 'devuelve JSON válido', pero eso no es un contrato fuerte. El modelo o la tool pueden incluir texto adicional, omitir campos, cambiar nombres o colar un error en un campo que el consumidor interpreta como dato. En una demo funciona; en producción crea ramas falsas de ejecución.

`outputSchema` mueve la expectativa al borde de la tool. Si `search_docs` promete una lista de documentos con `id`, `title`, `url`, `score` y `snippet`, el cliente puede rechazar respuestas incompletas, marcar la ejecución como degradada o pedir aprobación humana antes de continuar.

La diferencia para un agente de código es concreta: no es lo mismo leer 'encontré tres archivos importantes' que recibir un array validado de rutas, rangos, hashes y motivos. Lo segundo puede alimentar un diff, una revisión o una métrica sin depender de parsing frágil.

Validación en el cliente

La especificación dice que los servidores deben cumplir su schema y que los clientes deberían validar resultados estructurados. En una arquitectura seria, ambos lados hacen su parte: el servidor valida antes de responder y el cliente valida antes de confiar.

Errores como datos de control

La especificación distingue errores de protocolo JSON-RPC de errores de ejecución de la tool con `isError: true`. Esa distinción importa. Un nombre de tool desconocido o argumentos inválidos son problemas de protocolo; un 429 del upstream, una credencial caducada o una búsqueda sin resultados son estados operativos que el agente puede manejar.

Diseña errores recuperables con estructura: `code`, `retryAfterSeconds`, `safeToRetry`, `userActionRequired`, `detailsForLog` y `messageForModel`. El modelo no necesita ver todo el stack trace, pero sí necesita saber si debe reintentar, pedir permisos, reducir scope o parar.

Un agente que distingue `permission_denied` de `not_found` toma mejores decisiones. Un agente que solo recibe 'failed' tiende a repetir llamadas o inventar alternativas.

El objetivo no es describir todo el sistema al modelo. Es darle contratos pequeños, verificables y suficientes para avanzar.

Checklist de implementación

• Declara `outputSchema` en toda tool que alimente automatización.
• Devuelve `structuredContent` y un `TextContent` serializado para compatibilidad.
• Valida la salida en servidor antes de responder.
• Valida la salida en cliente antes de pasarla al modelo o ejecutar acciones.
• Separa datos, errores recuperables y errores de protocolo.
• Usa `resource_link` para artefactos grandes en vez de meter blobs en el resultado.
• Limita número de items, tamaños, URLs y MIME types.
• No confíes en anotaciones de tools desde servidores no verificados.
• Mide tokens consumidos por schemas y herramientas activas.
• Documenta qué campos son evidencia y cuáles son interpretación.