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.
La señal importante
Esto no elimina el criterio del modelo ni sustituye controles de seguridad. Sí reduce una clase común de fallos: herramientas que devuelven párrafos ambiguos, errores mezclados con datos, listas imposibles de parsear o respuestas que cambian de formato cuando el upstream falla.
La tesis operativa es simple: si una tool MCP alimenta decisiones, PRs, RAG, reporting, costes o acciones con permisos, su salida debe ser un contrato. Texto libre queda para explicación humana; structuredContent queda para automatización.
Qué cambió en MCP
La especificación de tools define inputSchema para parámetros y outputSchema como JSON Schema opcional para la salida esperada. Cuando una tool devuelve structuredContent, el servidor debe respetar su schema si lo ha declarado, y el cliente debería validarlo antes de pasarlo al modelo o a otra capa del workflow.
La misma página conserva compatibilidad hacia atrás: una tool que devuelve contenido estructurado debería incluir también una versión serializada en TextContent. Esto importa porque no todos los clientes MCP se actualizan al mismo ritmo, y un servidor que solo habla el formato nuevo puede romper consumidores antiguos.
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.
Diseño de schemas útiles
Empieza por el consumidor, no por la API upstream. Si el agente necesita decidir si abrir un PR, el schema debe incluir campos como confidence, changedFiles, testsRun, riskLevel y requiresHumanReview. Si la tool consulta documentación, incluye sourceUrl, retrievedAt, quote o summary, y separa claramente evidencia de interpretación.
Evita schemas enormes. Un outputSchema que replica toda la respuesta del proveedor consume contexto y obliga al modelo a mirar campos irrelevantes. Expón lo mínimo que el agente necesita para actuar y deja detalles voluminosos como resource links o artefactos recuperables.
Incluye estados explícitos: ok, partial, rate_limited, not_found, permission_denied. No hagas que el modelo infiera un fallo a partir de una frase. La investigación sobre MCP en producción señala precisamente la falta de semántica estructurada de errores como una brecha entre protocolo y operación real.
Resource links frente a blobs
MCP permite que una tool devuelva resource_link para apuntar a recursos que el cliente puede obtener o suscribirse después. Esto es mejor que incrustar siempre blobs largos en el resultado: el agente recibe una referencia con URI, nombre, descripción, MIME type y anotaciones, y decide si necesita cargar más contexto.
Para repositorios, esto encaja bien con resultados como archivos candidatos, logs de CI, trazas, documentos recuperados o reportes generados. El resultado estructurado puede contener ranking y metadatos; el resource link preserva el artefacto completo sin llenar el contexto inicial.
El patrón saludable es devolver índice primero y contenido después. Si el agente necesita todo, lo pedirá. Si solo necesita decidir el siguiente paso, no pagas tokens por material que no se usa.
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.
Lo que conviene comprobar
No pases structuredContent sin validar directamente a un pipeline que ejecuta acciones. Valida tipo, campos requeridos, longitudes, enumeraciones y límites numéricos. Si usas TypeScript, trata el valor como unknown hasta que pase por un parser o guardia de tipos. Si usas Python, valida con JSON Schema o modelos tipados antes de convertirlo en decisiones.
La validación también debe limitar coste: número máximo de items, tamaño máximo de snippets, URLs permitidas, MIME types aceptados y timeout por tool. Un schema correcto pero enorme puede ser igual de dañino para un agente que una respuesta inválida.
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.
Seguridad y confianza
Las anotaciones de tools son útiles, pero la especificación recuerda que los clientes deben tratarlas como no confiables salvo que vengan de servidores confiables. No conviertas readOnlyHint o una descripción amable en autorización. La política real vive en allowlists, permisos, aprobación humana, logs y validación de entradas y salidas.
Tampoco uses structuredContent como túnel para datos sensibles. Si el agente no necesita un token, un email completo o un payload privado, no lo devuelvas. La seguridad de MCP sigue dependiendo de límites clásicos: acceso mínimo, audience de tokens, evitar token passthrough, sanitizar salidas y registrar llamadas.
El contrato de salida ayuda a detectar anomalías, pero no reemplaza el threat model. Un resultado válido puede seguir siendo malicioso si proviene de una fuente no confiable.
Presupuesto de contexto
Los schemas también cuestan tokens. Un paper reciente sobre agentic RAG muestra que muchas definiciones de tools pueden competir con el contexto disponible para recuperar información. Aunque el resultado concreto dependa del modelo y del presupuesto, la lección es estable: cada campo de una tool debe justificar su presencia.
Comprime descripciones redundantes, usa nombres consistentes y evita incluir documentación completa dentro del schema. Para catálogos grandes de tools, agrupa capacidades por flujo y activa solo las necesarias para la tarea. Una tool perfectamente tipada pero siempre cargada puede degradar el rendimiento del agente.
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
outputSchemaen toda tool que alimente automatización. - Devuelve
structuredContenty unTextContentserializado 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_linkpara 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.
Un ejemplo mental
Imagina una tool inspect_ci_failure para un agente que arregla tests. Una salida pobre sería un bloque de texto con logs resumidos. Una salida útil tendría failingJobs, firstFailingCommand, suspectedFiles, confidence, reproCommand, logResourceLinks y requiresSecretAccess. Con eso, el agente puede decidir si tocar tests, código o configuración sin leer megabytes de log.
El reviewer humano también gana. En vez de preguntar "¿de dónde salió este cambio?", puede ver qué evidencia estructurada usó el agente, qué logs apuntó y qué nivel de riesgo declaró.
Ese es el valor real de structuredContent: no hacer que el modelo parezca más ordenado, sino dejar rastro técnico que otro sistema o una persona puedan comprobar.
Conclusión
MCP está creciendo como capa de integración para agentes, pero la fiabilidad no aparece por instalar más servidores. Aparece cuando cada tool tiene un contrato pequeño, validable y auditable.
Si hoy construyes servidores MCP, añade outputSchema pronto. Si consumes servidores MCP, valida structuredContent y trata texto libre como explicación, no como API. La diferencia parece menor hasta que un agente encadena tres tools y una respuesta ambigua se convierte en un PR incorrecto, una métrica falsa o una acción con permisos.
Publicado originalmente en devaisemanal.com.
Recibe una lectura semanal de herramientas IA para devs → — Cada martes: Claude Code, Cursor, Copilot, MCP, agentes y herramientas nuevas. En español y sin ruido.
Top comments (0)