mcp-capability-guard

La mayoría de los servidores MCP entregan al modelo una pistola cargada con un token portador compartido: una credencial, todas las herramientas, todas las llamadas. Este servidor hace que el modelo pida permiso para cada bala.

Es un servidor MCP pequeño y completo sobre un CRM ficticio en memoria (Larkspur Supply Co., siete contactos inventados) que demuestra la autorización de escritura mediante tokens de capacidad — un patrón extraído de un agente CRM de producción que ejecuto contra una libreta de contactos real de más de 12.000 contactos. Los datos aquí son ficticios; la aplicación de la política es la parte que se envía.

El diseño, en cinco capas

1. Superficie de herramientas por niveles. Las lecturas (list_contacts, get_contact) son gratuitas. Las escrituras no existen como herramientas individuales — no hay ninguna herramienta add_note ni delete_contact. Cada mutación fluye exactamente a través de dos llamadas: propose_write y luego execute_write.

2. Tokens de capacidad (la pieza central). propose_write acuña un warrant de un solo uso, limitado por TTL y vinculado a una mutación exacta — el token incorpora la mutación, no apunta a una, por lo que no hay tabla de búsqueda que envenenar ni ID que re-apuntar. execute_write presenta el token junto con la mutación, y el guardián verifica la igualdad campo por campo. Presentar un warrant con una mutación diferente no solo falla — quema el token, arrastrando consigo la escritura legítima del atacante.

3. Confirmación humana para el nivel destructivo. change_stage, remove_tag y delete_contact además requieren un "sí" explícito del operador mediante la elicitación de formularios de MCP, en un prompt que nombra la operación, el contacto y el payload en una sola frase. La solicitud se ejecuta antes de consultar al guardián, por lo que rechazarla nunca gasta el warrant — y un cliente sin canal de elicitación recibe rechazos de escrituras destructivas, no que se ejecuten silenciosamente. Fail closed, en ambas direcciones.

4. Un suelo que las capas superiores no pueden anular. Los contactos en la etapa Closed-Lost-DNC (no contactar, retención legal) rechazan toda escritura dentro del propio almacén, que no sabe nada de tokens ni de MCP. Un flujo totalmente aprobado — warrant válido, mutación coincidente, humano confirmado — sigue llegando a un callejón sin salida allí. Eso es lo que hace que esta sea una defensa en profundidad en lugar de una única puerta con tres carteles.

5. Un registro de auditoría de solo añadido que no puede filtrar warrants. Cada propuesta, confirmación, ejecución y rechazo se registra. Los ID de token entran en el registro solo como huellas digitales de 8 caracteres — y eso es una garantía en tiempo de compilación: el campo de huella digital contiene un tipo TypeScript de marca que solo la función de truncado puede producir. El texto libre se depura por valor también, porque los mensajes de rechazo del propio guardián nombran el token que rechazaron. (Esta es la misma disciplina de redacción por valor que en mi webhook-guard — allí para credenciales HTTP, aquí para garantías en vivo). read_audit es denegar por defecto: a menos que el servidor se compile con exposeAudit: true, la herramienta no está registrada en absoluto.

Related MCP server: tenant-scoped-crm

Véalo funcionar

npm install
npm run demo

La demo conecta el servidor real a un cliente con guion a través de un transporte MCP en memoria y narra ocho pasos: dos escrituras que se ejecutan (una reversible, una destructiva y confirmada), luego cinco ataques — repetición, engaño, una confirmación rechazada, un cambio de objetivo y una escritura totalmente aprobada contra el registro congelado — cada uno encuentra su rechazo tipado mientras el almacén permanece idéntico byte a byte. Termina leyendo el registro de auditoría y comprobando que ningún ID de token completo aparece en él. La demostración asegura cada expectativa en línea y sale con código distinto de cero en cualquier fallo, por lo que también sirve como prueba de humo y se ejecuta en CI en cada push.

npm install
npm run demo

npm test              # 158 offline tests
npm run typecheck     # strict TypeScript, no emit

Todo funciona sin conexión: sin claves API, sin red, sin variables de entorno, sin nada que configurar. Por eso CI ejecuta toda la suite, incluida la demo, en cada push sin secretos.

La evidencia está en los conjuntos de pruebas

Existen dos suites específicamente para mantener honestas las afirmaciones anteriores:

• test/structural.test.ts lee el código fuente como texto y fija la arquitectura: src/tools.ts es el único archivo que importa el SDK de MCP; el almacén no conoce nada por encima de él; los módulos de guardián y auditoría importan solo lo que declaran sus encabezados; la acuñación de tokens está confinada al guardián; la cadena token nunca aparece en src/audit.ts. Si una refactorización lleva código del SDK al almacén, esta suite falla antes de que lo haga cualquier comportamiento.

• test/adversarial.test.ts enfrenta un modelo hostil al servidor completamente conectado: omitir la propuesta, bait-and-switch con verificación de quema, re-apuntar un warrant a un contacto diferente, un asalto de aprobación total al registro congelado, un warrant expirado mediante un reloj inyectado, una evasión de confirmación y una verificación de integridad del registro con IDs de token elegidos por el atacante. Cada ataque debe encontrar su rechazo tipado exacto, y después de todos ellos el almacén debe permanecer sin cambios.

Los ~140 restantes test de unidad, guardián, auditoría y superficie de herramientas se cubren unitariamente, incluido el invariante de orden de que la confirmación se ejecuta antes de que el warrant pueda gastarse.

Versión y alcance

Construido sobre @modelcontextprotocol/sdk 1.30.0, que tiene como objetivo la revisión de MCP 2025-11-25. La revisión 2026-07-28 hace que los handles emitidos por el servidor y pasados como argumentos de herramienta ordinarios sean el mecanismo canónico para el estado entre llamadas (SEP-2567) — el token de capacidad en este repositorio es exactamente ese patrón, usado como primitiva de autorización, por lo que el diseño se traslada sin cambios al protocolo sin estado.

Dos dependencias en tiempo de ejecución: el propio SDK y zod, que es la dependencia par del SDK — los esquemas de herramientas son esquemas zod por diseño del SDK, por lo que no es una dependencia añadida tanto como la otra mitad del SDK. Nada más entra en el árbol. Los módulos del almacén, el guardián y la auditoría son TypeScript puro con cero importaciones más allá de node:crypto y los tipos de cada uno, lo que permite que 158 pruebas se ejecuten sin conexión en menos de medio segundo.

Qué no es esto. Este repositorio no implementa OAuth ni el rol de servidor de recursos de la especificación MCP. Esos resuelven un problema diferente: identificar quién es el cliente en el límite del transporte. Los tokens de capacidad gobiernan qué puede hacer un cliente autenticado, una escritura a la vez — los dos se componen en lugar de competir, y confundirlos es como los servidores terminan con un único token portador que autoriza todo. La identidad de transporte está deliberadamente fuera del alcance aquí para que la autorización siga siendo legible.

Limitaciones, declaradas claramente

• El CRM es ficticio y está en memoria. La persistencia, la concurrencia y las sesiones multiusuario son problemas reales que esta demo no tiene.

• Los tokens viven en la memoria del servidor; un reinicio los pierde. En producción, el mismo patrón se usa con un almacén duradero con la misma semántica de un solo uso.

• La confirmación por elicitación solo es tan buena como la representación que el cliente haga de ella. Un cliente que muestre al usuario un simple "¿Permitir?" en lugar de la frase del servidor debilita la garantía — lo que aboga por poner la frase completa en la solicitud, como hace este servidor, en lugar de omitirla.

• La marca de tiempo de las notas del almacén usa el reloj de pared, por lo que una línea de la salida de la demo varía entre ejecuciones. El guardián y el registro de auditoría usan relojes inyectados, por lo que son deterministas.

Adaptándolo

El patrón se aplica a cualquier servidor MCP cuyas escrituras tengan consecuencias: reemplace el almacén por su sistema, mantenga la división proponer/ejecutar, decida sus propios niveles, y mantenga la regla del suelo en la capa de datos en lugar de en la capa de herramientas. Los módulos de guardián y auditoría no importan nada de MCP y pueden extraerse por completo.

Licencia MIT.