El problema
Un servidor MCP expone una herramienta llamada search. La descripción simplemente indica: "busca datos". Al decidir si debe invocarla, el modelo se ve obligado a adivinar: ¿busca en qué fuente? ¿Con qué sintaxis de consulta? ¿Qué devuelve si no encuentra registros? Sin estas especificaciones en la propia descripción, el modelo comete errores frecuentes de selección o estructura argumentos con tipos inválidos — y cada fallo de este tipo cuesta un turno completo de reintento y recuperación.
MCP (Model Context Protocol) resuelve un problema estructural fundamental: sin él, cada integración entre un cliente (como Claude Code o un entorno de agentes) y una fuente de capacidades (una base de datos, una API interna, un sistema de archivos) requeriría código de acoplamiento punto a punto a ambos lados. MCP estandariza esta interfaz, desacoplando a quien provee la capacidad (el servidor) de quien la consume (el host). Sin embargo, este desacoplamiento solo funciona si el servidor se diseña con precisión — y ahí es donde se concentran los errores de arquitectura más comunes.
Las descripciones de herramientas son la verdadera interfaz
Una herramienta MCP deficiente no es la que contiene errores en su código de ejecución — es aquella cuya descripción no proporciona al modelo información suficiente para decidir cuándo y cómo invocarla. Una descripción rigurosa debe especificar:
- Qué hace la herramienta en términos concretos del dominio (no "busca datos", sino "busca tickets de soporte por ID de cliente o palabras clave en el título")
- Qué argumentos son obligatorios, cuáles opcionales y el formato esperado de cada uno
- Qué estructura devuelve la herramienta, incluyendo explícitamente el caso de "cero resultados encontrados"
- Restricciones operativas (límites de tasa, permisos de solo lectura vs. escritura, efectos secundarios)
Esto no es documentación para humanos — es la especificación legible por máquina que el modelo analiza para decidir si es la herramienta indicada para la solicitud actual. Una descripción ambigua se comporta como una función sin firma de tipos: solo funciona por accidente.
Ámbito de configuración: de proyecto vs. personal
MCP define niveles claros para configurar servidores, con consecuencias directas en la seguridad y la colaboración del equipo:
- Configuración de proyecto (
.mcp.json, versionada en el repositorio): reservada para servidores que todo el equipo debe utilizar de forma homogénea — por ejemplo, un servidor para acceder a la base de datos de staging. Al estar bajo control de versiones, cualquier cambio pasa por revisión de pull requests. - Configuración personal o local (
~/.claude.json): adecuada para servidores individuales o experimentales que se están probando antes de incorporarse al flujo compartido del equipo.
Incluir un servidor experimental no validado en el archivo .mcp.json de proyecto propaga inestabilidad a todos los integrantes del equipo. Por el contrario, dejar un servidor indispensable en la configuración personal de un desarrollador rompe las canalizaciones de CI y los entornos del resto del equipo. Un ámbito de configuración erróneo es motivo suficiente para invalidar una respuesta en un escenario de examen.
Los secretos utilizados por un servidor MCP (como tokens de API) jamás deben escribirse de forma literal en archivos de configuración versionados. El estándar universal es utilizar la expansión de variables de entorno (como ${GITHUB_TOKEN}), evitando almacenar credenciales en el historial de git.
Las descripciones y los resultados son superficie de ataque
Un servidor MCP de terceros (fuera de tu perímetro de confianza) puede devolver descripciones de herramientas o resultados de ejecución que contengan inyecciones de instrucciones diseñadas para alterar el comportamiento del modelo. Tratar toda descripción y todo resultado proveniente de servidores externos como datos no confiables — y nunca como instrucciones del sistema — es una regla obligatoria en integraciones seguras. Esto resulta crítico antes de promover cualquier servidor a la configuración del proyecto.
Recursos en lugar de llamadas repetitivas a herramientas
Cuando el contenido que expone un servidor es un catálogo amplio y relativamente estático (un esquema de base de datos o una taxonomía de categorías), exponerlo como un recurso MCP en lugar de exigir consultas iterativas a herramientas optimiza drásticamente el consumo de tokens y la latencia. El modelo puede inspeccionar el recurso directamente en una sola pasada.
Ponlo en práctica
En el laboratorio de esta lección escribirás un validador de contratos de herramientas MCP: dado un diccionario de definición, verificará si la descripción cubre los estándares mínimos (propósito concreto, tipos de parámetros, contratos de retorno) y detectará si las salidas de herramientas contienen patrones de inyección de instrucciones enmascaradas.