Introducción

Las primitivas de MCP son las principales unidades de diseño que conectan una aplicación de IA con capacidades y contexto externos. Al crear un servidor MCP, la cuestión central de diseño no es cuántos endpoints exponer. Es decidir si cada capacidad debe representarse como una herramienta, un recurso o un prompt. Elegir la primitiva incorrecta puede hacer que un agente no sea seguro, dificultar el descubrimiento del contexto u obligar a los usuarios a repetir instrucciones manualmente.

Las tres primitivas tienen distintos modelos de control e interacción. Las herramientas suelen estar controladas por el modelo: un agente puede decidir llamarlas cuando necesita realizar una acción o un cálculo. Los recursos suelen estar controlados por la aplicación: la aplicación host decide cuándo recuperar su contenido y presentarlo. Los prompts suelen estar controlados por el usuario: el usuario selecciona o invoca una plantilla de interacción reutilizable. Estas son convenciones habituales de diseño de MCP, no simplemente nombres distintos para la misma operación.

Esta lección presenta un método práctico de selección, reglas para el diseño de contratos y un pequeño helper de decisión. El objetivo es que la selección de primitivas sea predecible antes de comenzar la implementación.

Las tres primitivas

Una herramienta representa una operación que el modelo o el agente puede solicitar. La operación puede leer datos, transformar datos, llamar a un servicio o provocar un efecto secundario. Algunos ejemplos son buscar en un sistema de tickets, calcular los costes de envío, crear un borrador de factura o cancelar una reserva. Una herramienta debe tener un nombre específico, una descripción clara, un esquema de entrada definido y una salida que el modelo pueda interpretar.

Un recurso representa información direccionable identificada mediante un URI. Es adecuado para documentos, configuraciones, registros, esquemas, informes u otro contexto que una aplicación pueda cargar y poner a disposición del modelo. Un recurso puede ser estático, como un documento de políticas, o dinámico, como el registro de un cliente cuyo URI identifica una entidad actual. La lectura de un recurso debe tratarse como una recuperación de contexto, no como una instrucción para realizar una acción.

Un prompt es una plantilla de interacción reutilizable con un propósito definido. Puede especificar mensajes sugeridos, argumentos y la estructura esperada de una tarea. Por ejemplo, una aplicación de soporte puede ofrecer un prompt para resumir la reclamación de un cliente, mientras que una aplicación de revisión de código puede ofrecer un prompt para revisar una pull request. Un prompt no sustituye a una herramienta y no debe ocultar una operación que modifique el estado externo.

Elegir la primitiva adecuada

Comienza por identificar qué necesita obtener el usuario o el agente. Si el requisito es una acción, un cálculo, una consulta con parámetros o un efecto externo, empieza con una herramienta. El hecho de que una operación solo lea datos no la convierte automáticamente en un recurso. Una búsqueda parametrizada de pedidos actuales suele ser una herramienta, porque el modelo solicita un cálculo y recibe un resultado basado en los argumentos proporcionados.

Elige un recurso cuando el valor principal sea un contexto recuperable con una identidad estable. Un documento, como una política de devoluciones, el URI de un registro de base de datos o un informe generado, puede representarse como un recurso cuando la aplicación puede decidir cuándo debe cargarse. Los recursos son especialmente útiles cuando los usuarios necesitan explorar, adjuntar, almacenar en caché, actualizar o inspeccionar el contexto de forma independiente de la decisión de un agente.

Elige un prompt cuando el requisito sea empaquetar un patrón de conversación reutilizable para un usuario. Un prompt puede indicar al modelo cómo utilizar el contexto disponible, pero no debe hacerse pasar por una operación empresarial ejecutable. Si una solicitud dice «ayúdame a preparar una solicitud de reembolso», un prompt puede estructurar la conversación. Si dice «emite el reembolso», una herramienta debe ejecutar la operación autorizada.

Una prueba útil consiste en completar la frase «¿Quién inicia esta interacción?». Si el modelo debe decidir cuándo invocar una operación, utiliza una herramienta. Si la aplicación host debe recuperar o adjuntar información, utiliza un recurso. Si el usuario debe elegir un flujo de trabajo preparado, utiliza un prompt. Algunos flujos de trabajo utilizan legítimamente las tres primitivas en secuencia.

Diseñar contratos sólidos

Un buen contrato de herramienta minimiza la ambigüedad. Su nombre debe describir la operación, no la implementación. Su descripción debe indicar cuándo utilizarla, cuándo no utilizarla, qué permisos requiere y qué restricciones importantes se aplican. Los campos de entrada deben tener tipos explícitos, descripciones significativas, reglas de validación y valores acotados siempre que sea posible. Una herramienta que acepta un objeto de formato libre para cada solicitud dificulta que tanto los modelos como los servidores detecten errores.

Las salidas de las herramientas deben distinguir los datos correctos de la información de error. Devuelve resultados estructurados cuando el cliente necesite inspeccionar campos mediante programación, e incluye contenido conciso y legible para humanos cuando el resultado vaya a mostrarse a un modelo o a un usuario. No informes de éxito simplemente porque una solicitud haya llegado al servidor. En el caso de herramientas con efectos secundarios, el resultado debe dejar claro si la operación se completó, se rechazó, se completó parcialmente o solo se preparó como borrador.

El diseño de recursos depende de identificadores estables y contenido predecible. Utiliza URI que identifiquen el objeto de dominio o el documento sin incluir detalles accidentales de implementación. Decide si un recurso es inmutable, actualizable o versionado, y documenta cómo se gestiona el contenido obsoleto. Un recurso que contenga datos confidenciales también necesita una política de autorización; un URI es un identificador, no un permiso para leer los datos subyacentes.

El diseño de prompts debe exponer únicamente los argumentos que los usuarios o las aplicaciones puedan proporcionar razonablemente. La descripción de un prompt debe indicar el resultado previsto y el contexto requerido. Mantén las instrucciones operativas separadas de los datos del usuario y evita incorporar afirmaciones que el modelo deba tratar como autoritativas, a menos que la aplicación pueda mantenerlas. Un prompt puede recomendar una llamada a una herramienta, pero la autorización y la validación deben permanecer en las capas de la herramienta y del servidor.

Ejemplo práctico

Imagina una aplicación de atención al cliente con tres requisitos. Debe encontrar los pedidos abiertos de un cliente, proporcionar la política de devoluciones vigente y guiar a un agente durante una conversación sobre una devolución. El primer requisito es una consulta parametrizada contra un sistema activo, por lo que encaja con una herramienta. El segundo es un documento direccionable que la aplicación puede cargar cuando sea necesario, por lo que encaja con un recurso. El tercero es un patrón de conversación reutilizable seleccionado por el usuario, por lo que encaja con un prompt.

El siguiente helper local de JavaScript expresa esa regla de decisión. No es un servidor MCP ni sustituye el registro del protocolo. Su objetivo es hacer explícitas las revisiones de diseño antes de la implementación. El resultado incluye el primitive elegido y la razón que respalda la elección.

function chooseMcpPrimitive(requirement) {
  const text = requirement.toLowerCase();

  if (text.includes("perform") || text.includes("create") || text.includes("update") ||
      text.includes("delete") || text.includes("search") || text.includes("calculate") ||
      text.includes("send") || text.includes("live")) {
    return {
      primitive: "tool",
      reason: "The requirement describes an operation, computation, parameterized lookup, or side effect."
    };
  }

  if (text.includes("document") || text.includes("policy") || text.includes("record") ||
      text.includes("report") || text.includes("read") || text.includes("context")) {
    return {
      primitive: "resource",
      reason: "The requirement describes addressable information that an application can retrieve and attach as context."
    };
  }

  if (text.includes("guide") || text.includes("workflow") || text.includes("template") ||
      text.includes("conversation") || text.includes("summarize")) {
    return {
      primitive: "prompt",
      reason: "The requirement describes a reusable interaction pattern selected by a user or application."
    };
  }

  return {
    primitive: "review",
    reason: "The requirement does not provide enough information to distinguish action, context, and interaction template."
  };
}

console.log(chooseMcpPrimitive("search live open orders for a customer"));
console.log(chooseMcpPrimitive("read the current return policy document"));
console.log(chooseMcpPrimitive("guide an agent through a return conversation"));

La primera llamada debería producir una decisión sobre una tool, la segunda una decisión sobre un resource y la tercera una decisión sobre un prompt. El helper adopta deliberadamente una postura conservadora ante la ambigüedad. Una revisión de diseño real debería examinar la autorización, la actualidad de los datos, el control del usuario y si la operación tiene efectos secundarios antes de registrar cualquier elemento.

Modos de fallo comunes

Un error frecuente es exponer todas las capacidades como tools porque son fáciles de invocar para un agente. Esto crea un catálogo de tools sobredimensionado y anima al modelo a recuperar documentos mediante operaciones que deberían haber sido navegables o estar controladas por la aplicación. Separa el contexto de recuperación de las acciones, especialmente cuando el contexto es estable y puede almacenarse en caché.

Otro error es redactar una descripción de tool vaga. Un nombre como process_request no indica al modelo si busca, aprueba, envía o elimina algo. Las descripciones ambiguas aumentan las llamadas incorrectas y dificultan la revisión de autorizaciones. Indica directamente la operación, las entradas requeridas, las exclusiones importantes y el comportamiento de los efectos secundarios.

Un resource también puede diseñarse incorrectamente cuando su URI expone secretos, depende de elementos internos inestables de la base de datos o da a entender que existe acceso sin imponerlo realmente. Utiliza identificadores opacos cuando corresponda, valida la autorización en cada lectura y define cómo se informa del contenido ausente, obsoleto o no disponible. En el caso de los prompts, evita tratarlos como un límite de seguridad. Las instrucciones incluidas en un prompt no pueden sustituir la validación en el servidor.

Por último, no supongas que combinar primitives crea automáticamente un buen flujo de trabajo. Comprueba si el host expone los resources en el momento adecuado, si los usuarios pueden comprender los argumentos de los prompts y si las tools rechazan las solicitudes malformadas o no autorizadas. La observabilidad debería registrar el nombre del primitive, el resultado de la validación, el resultado de la autorización y la categoría del fallo, sin registrar valores sensibles innecesariamente.

Resumen

Las tools se utilizan para operaciones, cálculos, búsquedas parametrizadas y efectos secundarios. Los resources se utilizan para información direccionable que una aplicación puede recuperar y proporcionar como contexto. Los prompts se utilizan para patrones de interacción reutilizables que los usuarios pueden seleccionar o invocar. Sus diferencias se refieren tanto a la estructura de los datos como a quién controla la interacción.

Un proceso de diseño fiable comienza con el requisito, identifica quién inicia la interacción, comprueba si el resultado es una acción o un contexto y, a continuación, define un contrato limitado. Para cada primitive, las descripciones, los esquemas, los permisos, los errores y el comportamiento respecto a la actualidad de los datos deben ser explícitos.

Cuando un flujo de trabajo abarca varias áreas, compón los primitives de forma deliberada. Un usuario puede seleccionar un prompt, la aplicación puede adjuntar un resource y el modelo puede llamar a una tool. Mantener esas responsabilidades separadas produce un comportamiento más claro, una autorización más segura e integraciones MCP más fáciles de probar y mantener.