Patrones MCP seguros para agentes que mutan estado de negocio

Un servidor MCP mínimo que muestra tres patrones para dar a los agentes de IA acceso de escritura seguro a sistemas de negocio reales: fase de compuerta (phase-gating), validación antes de la mutación y registro de auditoría estructurado.

Esto es una demo, no un producto. El dominio (un sistema de inventario y órdenes de compra de juguete) existe solo para dar a los patrones algo concreto donde aplicarse — los patrones en sí son el punto, y son agnósticos al dominio.

Por qué existe esto

A los agentes de IA se les da cada vez más acceso de escritura a sistemas reales — órdenes, inventario, registros CRM, pronósticos. El modo de fallo común no es que el LLM subyacente sea poco fiable en algún sentido abstracto; es que las implementaciones a menudo confían en que el modelo "haga lo correcto" sin ninguna barrera estructural detrás. Cuando un agente alucina un estado, es manipulado por una inyección de prompt, o simplemente se equivoca en el orden de las operaciones, el resultado es una escritura incorrecta y silenciosa a un sistema que un humano ahora tiene que notar, diagnosticar y corregir después del hecho.

Los tres patrones siguientes no son investigación novedosa — son disciplina de ingeniería estándar para cualquier cosa que toque estado de producción, aplicada específicamente a llamadas de herramientas de agentes.

Related MCP server: sop-mcp

Los tres patrones

1. Fase de compuerta. Una operación de mutación (submit_purchase_order) no puede tener éxito a menos que una operación correspondiente de lectura/vista previa (draft_purchase_order) haya ocurrido primero, en la misma sesión. Esto se aplica en código — un error duro, no una instrucción de prompt que el modelo pueda ignorar o de la que pueda ser convencido. El mensaje de error le dice al llamador exactamente qué hacer a continuación, que es lo que permite que un agente se autocorrija en lugar de simplemente fallar.

2. Validación antes de la mutación. Cada verificación — ¿existe el SKU, es la cantidad razonable, excede esto un umbral de orden razonable? — se ejecuta contra una representación pura del cambio propuesto, antes de que se escriba nada. La validación nunca tiene efectos secundarios. Y críticamente: todas las verificaciones se ejecutan independientemente de fallos anteriores, para que un llamador vea todos los problemas a la vez en lugar de arreglar uno, reenviar y encontrarse con el siguiente.

3. Registro de auditoría estructurado. Cada llamada de herramienta se registra — incluyendo las bloqueadas y rechazadas, no solo las mutaciones exitosas. Un rastro de auditoría que guarda silencio sobre intentos denegados está perdiendo exactamente los eventos que más vale la pena revisar después: ¿qué intentó el agente que fue detenido, y por qué?

La demo

• examples/happy_path.md — borrador → revisión → envío, con salida real capturada

• examples/blocked_paths.md — cinco formas en que la capa de seguridad realmente detiene una llamada mala, también con salida real

Pruébalo tú mismo

pip install -r requirements.txt
pytest tests/ -v          # 17 tests, exercises every pattern above
python server.py          # runs the MCP server over stdio

Las pruebas son la prueba real, no la prosa anterior. Si quieres verificar una afirmación en este README, la prueba correspondiente es una mejor fuente de verdad que mi descripción de ella.

Estructura

server.py              # MCP tool definitions — thin, delegates everywhere
safety/
  phases.py             # session state + the phase gate itself
  validation.py         # pure validation functions
  audit.py               # structured logging, including failures
domain/
  inventory.py           # toy in-memory "database"
  purchase_orders.py    # draft/commit data + transformations
tests/                   # one file per pattern, ~17 tests total
examples/                 # real captured walkthroughs

safety/ y domain/ no se importan entre sí en la dirección que esperarías que una división de "lógica de negocio" y "salvaguardas" invirtiera: la capa de dominio no tiene idea de que existen sesiones o aprobación. La compuerta vive completamente fuera de ella, en safety/phases.py, que decide si domain.purchase_orders.commit_draft() se alcanza alguna vez. Esa separación es deliberada — es lo que hace posible razonar sobre las propiedades de seguridad sin tener que razonar también sobre la lógica de inventario al mismo tiempo.

Lo que esto no es

No es código de producción. Sin base de datos real — el inventario es un dict de Python. Sin autenticación. El estado de sesión está en memoria y es de un solo proceso. Esto existe para hacer que los patrones de seguridad sean inspeccionables y comprobables de forma aislada, no para ser un sistema que alguien deba desplegar.

Antecedentes

Diseñé y construí servidores MCP de producción (Go, Kubernetes) durante mi pasantía en Eli Lilly, incluyendo acceso a herramientas con fase de compuerta y validación obligatoria antes de cualquier operación de despliegue que mutara estado. Esta demo está construida desde cero, en un dominio diferente, sin usar nada de ese código — aísla los mismos patrones subyacentes para que puedan leerse, ejecutarse y probarse sin requerir acceso a nada propietario.