Tool, resource o prompt: cómo decidir qué exponer en un servidor MCP
Aprende a modelar bien un servidor MCP desde el principio: cuándo conviene exponer una tool, cuándo un resource y cuándo un prompt para no crear servidores confusos ni caros de mantener.
La mayoría de servidores MCP flojos no fallan por sintaxis, sino por modelado. Exponen demasiadas tools, convierten cualquier dato en acción o mezclan prompt, contexto y ejecución sin criterio.
La decisión importante no es solo qué puede hacer tu servidor, sino cómo lo descubre y lo usa el host. Esa forma cambia la experiencia del modelo, la seguridad operativa y el coste de mantenimiento.
Una tool sirve para ejecutar una acción o resolver una operación. Un resource sirve para ofrecer contexto legible. Un prompt sirve para empaquetar un flujo o una intención reutilizable.
Cuando se confunden estas capas, el resultado suele ser un servidor difícil de entender: nombres ambiguos, schemas inflados, recursos que deberían ser plantillas dinámicas y prompts que intentan sustituir la lógica del sistema.
- Modelar bien una capacidad evita servidores difíciles de descubrir, usar y mantener.
- Un servidor MCP no gana valor por tener más primitivas, sino por exponerlas con la forma correcta. El host y el modelo necesitan saber si algo debe leerse, ejecutarse o invocarse como plantilla guiada.
- Si publicas como tool algo que en realidad es contexto estable, obligas al modelo a pedir una acción innecesaria. Si publicas como resource algo que cambia según parámetros del usuario, puedes volver rígido un flujo que debería ser flexible.
- La primera pregunta útil no es técnica. Es esta: ¿quiero dar contexto, ejecutar una acción o encapsular un flujo guiado?
- Una tool existe para hacer algo, no para disfrazar contexto.
La decisión importa
Modelar bien una capacidad evita servidores difíciles de descubrir, usar y mantener.
Un servidor MCP no gana valor por tener más primitivas, sino por exponerlas con la forma correcta. El host y el modelo necesitan saber si algo debe leerse, ejecutarse o invocarse como plantilla guiada.
Si publicas como tool algo que en realidad es contexto estable, obligas al modelo a pedir una acción innecesaria. Si publicas como resource algo que cambia según parámetros del usuario, puedes volver rígido un flujo que debería ser flexible.
La primera pregunta útil no es técnica. Es esta: ¿quiero dar contexto, ejecutar una acción o encapsular un flujo guiado?
Cuándo usar tool
Una tool existe para hacer algo, no para disfrazar contexto.
Usa una tool cuando el servidor deba ejecutar una operación con inputs definidos: consultar una API externa, buscar en una base de datos, crear un registro, lanzar una acción o transformar información.
Una buena tool tiene nombre claro, descripción orientada al modelo y `inputSchema` mínimo. Cada parámetro debe justificar su existencia.
Si la operación tiene efectos, coste o riesgo, conviene que la tool lo deje claro con sus metadatos y que el cliente pueda pedir confirmación.
- Buena señal: hay una operación concreta con entrada y salida.
- Mala señal: la tool solo devuelve texto estático que no depende de una acción.
- Buena señal: el `inputSchema` es breve, explícito y validable.
- Mala señal: la tool intenta resolver tres tareas distintas a la vez.
Cuándo usar resource
Un resource ofrece contexto legible que el host puede recuperar e incluir cuando lo necesita.
Usa un resource cuando el valor principal sea la lectura de información: documentación, archivos, esquemas, registros, configuración, contenido de un repositorio o datos que tienen sentido como contexto recuperable.
Los resources funcionan especialmente bien cuando la URI y el tipo de contenido ayudan al cliente a descubrir qué leer y cómo tratarlo.
Si el contexto es dinámico, no siempre necesitas convertirlo en tool. A veces un resource template parametrizado describe mejor la información que una acción ejecutable.
Cuándo usar prompt
Un prompt no sustituye a tools y resources; los organiza alrededor de una intención.
Usa un prompt cuando quieras ofrecer una plantilla reutilizable para iniciar una tarea frecuente: revisar una incidencia, preparar un resumen técnico o analizar un cambio de arquitectura.
Los prompts son especialmente útiles cuando el usuario o el host se benefician de una entrada guiada, de argumentos claros y de una estructura que conecte bien recursos y herramientas disponibles.
Un mal uso frecuente es crear prompts para esconder carencias del servidor. Si hace falta contexto, expón resources. Si hace falta acción, expón tools. El prompt solo debería ordenar el flujo.
Errores comunes
Los fallos de diseño suelen verse pronto en la experiencia del modelo.
Una prueba rápida: si un tercero no entiende en pocos segundos qué expone tu servidor y por qué está modelado así, todavía falta claridad de diseño.
Caso guiado
Imagina un servidor MCP para documentación interna de un equipo. El contenido del handbook, la arquitectura del sistema y los runbooks deberían salir como resources. La búsqueda de incidencias por ID o la consulta a una API de despliegues encaja mejor como tool. Un flujo como 'preparar resumen de incidencia para handoff' tiene más sentido como prompt.
Ese reparto deja cada cosa en su sitio: contexto estable como lectura, operaciones concretas como acción y flujos repetibles como plantilla. El servidor resulta más fácil de descubrir y el modelo tiene menos oportunidades de elegir mal la primitiva.
Este criterio conecta con la siguiente etapa del curso: diseñar contratos de entrada y salida con schemas útiles, no solo válidos.
