AgentGuard MCP

Autorización basada en identidad para agentes de IA.

AgentGuard MCP es un servidor protegido del Model Context Protocol que otorga a los agentes de IA identidades de máquina distintas, aplica permisos OAuth de privilegio mínimo, aplica políticas de autorización contextuales y pausa acciones sensibles para la aprobación humana autenticada antes de la ejecución.

Es el backend de autorización para AgentGuard.

Producto en vivo: https://agentguard-eight.vercel.app

¿Por qué AgentGuard?

Dar a un agente de IA acceso a una herramienta es fácil.

Controlar qué agente puede usar qué herramienta, bajo qué condiciones y cuándo debe intervenir un humano es más difícil.

AgentGuard separa esas preocupaciones:

• Auth0 autentica identidades de máquina y humanas.

• Los alcances OAuth definen qué puede solicitar cada identidad de máquina.

• La política de AgentGuard evalúa el contexto de la acción.

• La aprobación humana controla las operaciones de mayor riesgo.

• Supabase persiste el estado de aprobación y los eventos de auditoría de seguridad.

• MCP expone las herramientas protegidas a los entornos de ejecución de IA.

Por lo tanto, un agente puede ser autenticado sin que se le confíe automáticamente la realización de cada acción.

Related MCP server: gov-mcp

Arquitectura

flowchart LR
    A[AI Agent] --> B[Auth0 Machine Identity]
    B --> C[OAuth Access Token]
    C --> D[AgentGuard MCP Server]

    D --> E{Required Scope?}

    E -->|Missing| F[DENY]
    E -->|Granted| G[Contextual Policy]

    G -->|Low Risk| H[ALLOW]
    G -->|Sensitive| I[APPROVAL_REQUIRED]
    G -->|Forbidden| F

    I --> J[(Supabase Approval)]
    J --> K[Auth0 Human Login]
    K --> L{Human Decision}

    L -->|Approve| M[APPROVED]
    L -->|Deny| N[DENIED]

    M --> O[Agent Retries Approved Action]
    O --> P[Identity + Approval Verification]
    P --> Q[Execute Once]

    F --> R[(Audit Events)]
    H --> R
    I --> R
    N --> R
    Q --> R

Modelo de seguridad

AgentGuard utiliza dos clases de identidad distintas.

Identidades de máquina

Cada runtime autónomo recibe una identidad separada de Auth0 Machine-to-Machine.

Ejemplos de identidades de demostración:

Un agente de ventas no puede emitir reembolsos simplemente porque otro agente pueda hacerlo.

La capa de autorización verifica los alcances incluidos en el token de acceso OAuth del llamante antes de que se ejecute la herramienta protegida.

Identidades humanas

Los operadores humanos se autentican por separado a través de una Aplicación Web Regular de Auth0 en el panel de AgentGuard.

Las identidades de máquina y las identidades humanas están separadas intencionalmente.

Por lo tanto, una solicitud sensible puede verse así:

Finance Agent
    ↓
Authenticated machine identity
    ↓
finance:refund scope
    ↓
Contextual policy
    ↓
APPROVAL_REQUIRED
    ↓
Authenticated human administrator
    ↓
APPROVED
    ↓
Finance Agent executes approved action

Capas de autorización

AgentGuard aplica la autorización en capas.

1. Autenticación

El servidor MCP valida el token de acceso de Auth0 y establece la identidad del llamante.

2. Autorización de alcances OAuth

Las herramientas protegidas declaran los alcances necesarios para invocarlas.

Ejemplo:

@require_scopes(["finance:refund"])

Si el llamante no tiene el alcance requerido, la ejecución se detiene inmediatamente.

3. Política contextual

Superar la verificación OAuth no autoriza automáticamente la ejecución.

AgentGuard evalúa el contexto de la acción solicitada.

Las reglas de demostración actuales incluyen:

Refund <= $500
→ ALLOW

Refund > $500
→ APPROVAL_REQUIRED

Customer data export
→ APPROVAL_REQUIRED

Customer deletion
→ DENY

4. Aprobación humana

Las operaciones sensibles se escriben en el almacén de aprobaciones y se pausan.

Un humano autenticado por separado puede aprobar o denegar la solicitud a través del panel de AgentGuard.

5. Ejecución vinculada a la aprobación

Una acción aprobada solo puede ser ejecutada por la identidad de máquina que la solicitó originalmente.

AgentGuard verifica:

• que la aprobación exista

• que el estado de la aprobación sea APPROVED

• que la aprobación pertenezca a la identidad solicitante

• que la acción de aprobación coincida con la herramienta solicitada

• que la aprobación no se haya ejecutado ya

6. Protección contra repetición

Después de una ejecución exitosa:

APPROVED
→ EXECUTED

Un segundo intento de ejecución se deniega y se registra como evento de seguridad.

Casos de seguridad demostrados

El proyecto incluye tres escenarios persistidos que también son visibles en la demostración pública de AgentGuard.

Aprobado por humano

Finance Agent
→ finance:refund scope verified
→ requests $750 refund
→ policy requires approval
→ human administrator approves
→ Finance Agent executes
→ ALLOW
→ approval becomes EXECUTED

Denegado por humano

Finance Agent
→ finance:refund scope verified
→ requests $750 refund
→ policy requires approval
→ human administrator denies
→ Finance Agent attempts execution
→ DENY

Alcance bloqueado

Sales Agent
→ attempts issue_refund
→ missing finance:refund
→ DENY

Contextual policy is never evaluated.
Human review is never reached.

Esto demuestra la diferencia entre:

• autenticación

• autorización

• política contextual

• control humano

Herramientas MCP

La demostración actual expone cinco herramientas MCP protegidas.

search_accounts

Buscar cuentas de CRM.

Alcance requerido:

crm:read

issue_refund

Solicitar o ejecutar un reembolso según la política.

Alcance requerido:

finance:refund

Política:

amount <= $500 → ALLOW
amount > $500  → APPROVAL_REQUIRED

list_pending_approvals

Lista las solicitudes de aprobación pendientes de revisión.

Alcance requerido:

agent:manage

approve_action

Ruta de aprobación administrativa de MCP utilizada durante las pruebas de runtime de máquina.

Alcance requerido:

agent:manage

La aplicación de portafolio también admite una ruta de aprobación humana preferida a través del panel de Next.js protegido por Auth0.

execute_approved_refund

Ejecuta un reembolso ya aprobado.

Alcance requerido:

finance:refund

El servidor verifica que la aprobación pertenezca a la identidad de máquina que llama antes de la ejecución.

Ciclo de vida de las aprobaciones

Los registros de aprobación utilizan cuatro estados:

PENDING
APPROVED
DENIED
EXECUTED

Ciclo de vida exitoso típico:

PENDING
   ↓
APPROVED
   ↓
EXECUTED

Ciclo de vida denegado:

PENDING
   ↓
DENIED

La revisión y la aprobación se almacenan por separado.

Esto permite a AgentGuard representar:

DENIED
reviewed_by = Human Administrator
approved_by = null

sin tratar incorrectamente una denegación humana como una aprobación.

Eventos de auditoría

AgentGuard registra decisiones de autorización y políticas en Supabase.

Ejemplos de eventos incluyen:

ALLOW
DENY
APPROVAL_REQUIRED
APPROVED

Los metadatos de seguridad pueden incluir:

• alcances concedidos

• alcances faltantes

• fallos de autorización

• IDs de aprobación

• identidad solicitante

• contexto de la acción

• intentos de repetición

• revisor humano

• identificadores de cuenta/recurso

Ejemplo de fallo de alcance:

{
  "action": "issue_refund",
  "decision": "DENY",
  "required_scope": "finance:refund",
  "reason": "Missing required scopes: ['finance:refund']",
  "metadata": {
    "granted_scopes": [
      "crm:read",
      "crm:write",
      "support:read"
    ],
    "missing_scopes": [
      "finance:refund"
    ],
    "security_event": "authorization_failure"
  }
}

Los secretos y tokens de acceso nunca deben escribirse en el registro de auditoría.

Estructura del repositorio

agentguard-mcp/
│
├── database/
│   └── schema.sql
│
├── src/
│   ├── auth0/
│   │   ├── __init__.py
│   │   ├── authz.py
│   │   ├── errors.py
│   │   └── middleware.py
│   │
│   ├── approvals.py
│   ├── audit.py
│   ├── config.py
│   ├── database.py
│   ├── policy.py
│   ├── server.py
│   ├── tools.py
│   └── __init__.py
│
├── .env.example
├── .gitignore
├── pyproject.toml
└── README.md

Base de datos

AgentGuard actualmente utiliza Supabase/Postgres para:

approvals

Almacena solicitudes sensibles y su ciclo de vida de revisión.

Los campos importantes incluyen:

requesting_identity
action
payload
reason
status

reviewed_by
reviewed_at

approved_by
approved_at

executed_at

audit_events

Almacena decisiones de seguridad y contexto de ejecución.

Los campos importantes incluyen:

identity
action
decision
required_scope
reason
approval_id
metadata
created_at

La seguridad a nivel de fila está habilitada en ambas tablas.

No se crean políticas públicas de navegador.

Los componentes de servidor de AgentGuard de confianza acceden a la base de datos utilizando credenciales solo de servidor.

Ver:

database/schema.sql

Configuración local

Requisitos

• Python 3.10+

• inquilino de Auth0

• proyecto de Supabase

• aplicaciones Auth0 Machine-to-Machine

• API de Auth0 configurada para el recurso MCP

Clonar

git clone https://github.com/haisamar/agentguard-mcp.git
cd agentguard-mcp

Crear un entorno virtual

Windows:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Instalar dependencias

Usando Poetry:

pip install poetry
poetry install

O instala las dependencias requeridas manualmente si lo prefieres.

Configurar el entorno

Copia:

.env.example

a:

.env

y configura tus propias credenciales.

Nunca hagas commit de .env.

Variables de entorno requeridas

AUTH0_DOMAIN=
AUTH0_AUDIENCE=http://localhost:3001/
MCP_SERVER_URL=http://localhost:3001/
PORT=3001

SALES_AGENT_CLIENT_ID=
SALES_AGENT_CLIENT_SECRET=

FINANCE_AGENT_CLIENT_ID=
FINANCE_AGENT_CLIENT_SECRET=

ADMIN_AGENT_CLIENT_ID=
ADMIN_AGENT_CLIENT_SECRET=

SUPABASE_URL=
SUPABASE_SECRET_KEY=

Permisos de la API de Auth0

La API de AgentGuard actualmente define permisos que incluyen:

crm:read
crm:write

support:read
support:write

finance:read
finance:refund

customer:export

agent:manage

Las aplicaciones Machine-to-Machine deben recibir solo los permisos necesarios para su rol.

Ejecutar el servidor MCP

Desde la raíz del repositorio:

python -m src.server

Servidor predeterminado:

http://localhost:3001/

Endpoint de MCP:

http://localhost:3001/mcp

Metadatos de recursos protegidos:

http://localhost:3001/.well-known/oauth-protected-resource

Pruebas con MCP Inspector

Inicia el MCP Inspector:

npx -y @modelcontextprotocol/inspector

Conéctate usando:

Transport:
Streamable HTTP

URL:
http://localhost:3001/mcp

Usa un token de acceso Auth0 Machine-to-Machine en el encabezado de autorización:

Authorization: Bearer <ACCESS_TOKEN>

No hagas commit ni expongas tokens de acceso.

Frontend

La interfaz de producto complementaria de AgentGuard está disponible aquí:

Repositorio

https://github.com/haisamar/agentguard

Demostración en vivo

https://agentguard-eight.vercel.app

Proporciona:

• página pública del producto

• demostración pública de seguridad saneada

• panel de administración protegido por Auth0

• controles humanos de aprobación/denegación

• visualización de identidad de máquina vs. humana

• explorador de trazas de autorización

• inspección interactiva de eventos de seguridad

• historial de aprobaciones

Tecnología

AgentGuard combina:

Auth0
OAuth 2.0
Model Context Protocol
Python
FastMCP
Starlette
Supabase / PostgreSQL
Next.js
Human-in-the-loop authorization

Principio de diseño

AgentGuard se basa en una idea simple:

Que un agente de IA esté autenticado no debería significar que tenga autoridad ilimitada.

La autenticación demuestra quién es el agente.

Los alcances OAuth determinan qué categoría de acciones puede solicitar.

La política contextual determina si esa acción específica puede ejecutarse de forma autónoma.

La aprobación humana proporciona un límite de identidad separado para decisiones de alto riesgo.

Alcance actual

AgentGuard es un prototipo de seguridad de portafolio, no una plataforma IAM de producción.

Las limitaciones actuales incluyen intencionalmente:

• las reglas de política de demostración están definidas en código

• las identidades de máquina están mapeadas a roles de demostración

• el backend de MCP está diseñado para un despliegue controlado/local

• la autorización de administración humana actualmente utiliza una lista de permitidos de administradores a nivel de aplicación

• la gestión de políticas aún no se expone a través de un plano de control

• la inmutabilidad de los eventos de auditoría no se aplica en la capa de base de datos

• el bloqueo distribuido para la ejecución concurrente está fuera del alcance de la demostración actual

Estos límites están documentados intencionalmente en lugar de ocultarse.

Posibles extensiones

Las versiones futuras podrían añadir:

• administración humana basada en roles de Auth0

• política como código

• versionado de políticas

• registro de identidad de agentes

• federación de identidades de cargas de trabajo

• autorización delegada

• aprobaciones con límite de tiempo

• autorización a nivel de recurso

• expiración de aprobaciones

• aislamiento a nivel de organización

• eventos de auditoría firmados

• exportación SIEM

• simulación de políticas

• despliegue de MCP en producción

• herramientas MCP adicionales y servidores de recursos

Proyecto relacionado

Frontend de AgentGuard:

https://github.com/haisamar/agentguard