mcp-policy-gateway

Una implementación de referencia de servidor MCP con políticas primero. Muestra cómo darle al agente herramientas útiles sin permitir que el modelo decida la autorización, cruce límites de tenant, filtre PII directa o ejecute mutaciones de alto impacto por su cuenta.

Esto es una implementación de portafolio/referencia. Cada registro es sintético; no es software de producción y no pretende integrarse con un banco, procesador de pagos o sistema de clientes.

Por qué existe esto

Una demo común de MCP expone una API cruda al modelo y trata una llamada de herramienta exitosa como un modelo de seguridad. Este proyecto adopta la posición opuesta:

• La política es determinista. El modelo no puede autorizarse a sí mismo.

• El límite de tenant se aplica en el servidor. Un argumento de herramienta no puede cambiar de tenant.

• La salida de la herramienta se minimiza. El resumen de cuenta excluye intencionalmente el nombre del propietario y el correo electrónico.

• Las acciones de alto impacto se detienen en una puerta de aprobación. Una solicitud de congelación no produce ningún cambio de estado.

• Cada decisión es auditable. Los resultados de permitir, denegar y requerir aprobación crean eventos de auditoría estructurados.

• Las solicitudes de mutación requieren una razón y una clave de idempotencia.

Related MCP server: scopeguard-mcp

Arquitectura

MCP client / agent
       │ tool call
       ▼
FastMCP stdio adapter
       │ verified principal (demo fixture here)
       ▼
GatewayService ──► PolicyEngine ──► allow / deny / require approval
       │                 │
       ▼                 ▼
synthetic domain data   structured audit event

En un despliegue de producción, el principal se derivaría de una identidad/sesión verificada fuera del contexto del modelo. Nunca aceptes tenant_id, roles o ámbitos de un argumento de herramienta o salida del modelo.

Herramientas

Inicio rápido

Requiere Python 3.11+.

python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
.venv/bin/ruff check .

Ejecutar como servidor MCP stdio:

.venv/bin/mcp-policy-gateway

El adaptador usa un principal de demostración deliberadamente fijo para exploración local. La propagación real de identidad se documenta intencionalmente como una preocupación de integración de producción en lugar de simularse aquí.

Controles de abuso demostrados

Las pruebas demuestran que la puerta de enlace:

1. deniega a un agente de tenant_red que intenta leer datos de tenant_blue;

2. deniega una llamada de herramienta sin su ámbito requerido;

3. no devuelve el nombre del propietario ni el correo electrónico a través de la herramienta de resumen;

4. devuelve require_approval en lugar de mutar el estado de la cuenta; y

5. rechaza solicitudes de cambio de estado que omiten una razón o clave de idempotencia.

Modelo de amenazas y no objetivos

Ver THREAT_MODEL.md. El diseño es intencionalmente limitado: demuestra un límite de política alrededor de las herramientas MCP, no infraestructura de identidad completa, almacenamiento de auditoría duradero, gestión de secretos o un sistema de pagos/contabilidad.

Recorrido para entrevistas

Una forma concisa de explicar el proyecto:

Diseñé el límite MCP para que el modelo pueda razonar sobre datos seguros y con ámbito, pero no pueda decidir el acceso ni ejecutar acciones de alto impacto. La autorización es determinista, el aislamiento de tenant se aplica en el servidor, la superficie de herramientas minimiza la PII y las mutaciones sensibles terminan en una puerta de aprobación humana auditable.

Desarrollo

.venv/bin/pytest
.venv/bin/ruff check .

CI ejecuta ambas comprobaciones en pushes y pull requests.

Licencia

MIT. Ver LICENSE.