Diseño de capacidades

Una capacidad es la habilidad más pequeña y describible de un sistema: tipada, con verificación de permisos, auditable e igualmente utilizable por personas y agentes. MCP-first no comienza con pantallas, sino con estas capacidades. Solo cuando el conjunto de capacidades está completo surgen la aplicación web, la app móvil, la CLI y las interfaces de agente como clientes sobre ellas.

Los siete bloques de construcción

MCP-first modela cada capacidad con siete elementos estructurales.

Resources

Datos y contextos que pueden leerse. Los recursos suministran al agente contexto procesado , no tablas de base de datos crudas, sino vistas filtradas y orientadas a un propósito sobre el estado del sistema.

Tools

Acciones que el sistema puede ejecutar. Cada herramienta tiene un esquema de entrada tipado, un esquema de salida, un esquema de error y un esquema de auditoría. Una herramienta es lo que un botón en la aplicación web tan solo representa.

Prompts / Workflows

Flujos predefinidos que guían a un agente a través de procesos complejos y de múltiples pasos. Los flujos de trabajo definen qué herramientas deben invocarse en qué orden y con qué contexto , y dónde se esperan entradas humanas.

Policies

Reglas, permisos, niveles de protección y procesos de aprobación. Las políticas deciden quién puede ver, invocar y ejecutar autónomamente una capacidad. No son una capa que se añade después , son parte de la definición de la capacidad.

Audit Events

Cada acción genera una entrada de auditoría: quién, qué, cuándo, con qué aprobación, con qué resultado. Los Audit Events no son una extensión operativa opcional, sino un componente obligatorio de cada capacidad.

Human Confirmation Gates

Mecanismos mediante los cuales el agente debe solicitar activamente al usuario confirmación antes de ejecutar una acción. Los Confirmation Gates están declarados de forma declarativa en la capacidad, no implementados ad hoc en la UI.

Risk Metadata

Cada capacidad lleva un nivel de riesgo: low, medium, high, critical o forbidden_for_ai. Estos metadatos controlan el filtrado de descubrimiento, la obligación de confirmación y la Step-up-Auth, y están disponibles de forma legible por máquina en el Tool Contract.

Lo que cada entidad debería ofrecer

Independientemente del dominio funcional, cada entidad necesita un conjunto base consistente de capacidades.

Capacidades base por entidad

entity.list Devolver lista filtrada
entity.search Búsqueda de texto completo con scoping
entity.get Entidad individual con contexto
entity.create Crear nueva entidad
entity.update Cambiar campos, idempotente
entity.archive Desactivar en lugar de eliminar
entity.audit Consultar historial de cambios
entity.permissions Consultar permisos efectivos
entity.related Cargar entidades relacionadas
entity.recommended_next_actions Sugerencias de acción para agentes

Action Layer primero

Cada función se implementa primero como una acción en la capa de acciones central. Solo después surge el adaptador de interfaz correspondiente.

Action: create_project

Utilizada desde:
  Aplicación web
  App móvil
  MCP Tool
  Worker
  CLI

De este modo no hay implementación doble: cuando un botón de la aplicación web invoca create_project y un agente hace lo mismo, ambos utilizan el mismo código, las mismas validaciones, los mismos Audit Events.

Build capabilities once. Expose them everywhere.

Claim central

El servidor MCP es un adaptador

El servidor MCP no contiene lógica de negocio. Es un adaptador delgado entre el cliente del agente y la capa de acciones.

Sus tareas:

Discovery, ¿qué herramientas y recursos existen en este contexto?
Schema Exposure, descripción tipada de entradas, salidas y errores
Auth Context Mapping, mapear el token del cliente al contexto de usuario y tenant
Policy Checks, ¿puede este agente invocar esta herramienta en este contexto?
Audit Logging, escribir Execution-Events para cada ejecución de herramienta

Entradas y salidas tipadas

Cada herramienta define cuatro esquemas:

Esquema	Propósito
Input Schema	¿Qué parámetros espera la herramienta, qué tipos, qué campos son requeridos?
Output Schema	¿Qué devuelve la herramienta en caso de éxito?
Esquema de error	¿Qué códigos de error son posibles, `permission_denied`, `confirmation_required`, `policy_violation`?
Esquema de auditoría	¿Qué se escribe en el Audit Event?

Sin estructuras JSON sueltas. Los agentes, al igual que los compiladores y las pruebas, dependen de estos esquemas. Las salidas no tipadas imponen lógica de adivinanza en el lado del cliente.

Idempotencia

Muchas herramientas deberían ser idempotentes: producir el mismo resultado ante la misma petición, sin generar duplicados innecesarios.

create_download_link(fileId, expiresAt)

Si para fileId ya existe un enlace válido con el mismo expiresAt, la herramienta devuelve ese enlace en lugar de crear uno segundo. Esto reduce los errores del agente en reintentos y hace los flujos de trabajo más robustos ante interrupciones de red.