# Permisos del agente MCP

Qué puede hacer un agente MCP: permisos de su humano, alcance por proyecto y VPS, solo lectura y operaciones siempre prohibidas.

Fuente: https://ardumaker.com/docs/permisos-mcp/

- Categoría: Inteligencia artificial y agentes
- Estado: Disponible
- Requisitos: Una cuenta de ArduMaker que autoriza al agente; Un agente conectado al servidor MCP (ver [Servidor MCP](https://ardumaker.com/docs/servidor-mcp))
- Herramientas MCP (Solo leen): `ver_contexto_inicial`

## ¿Qué permite hacer?

- Limitar un agente a ciertos proyectos y, por separado, a ciertos VPS.
- Dejar un agente en solo lectura: no ve ni puede llamar herramientas que modifican datos.
- Cambiar el alcance o el modo desde `/me` sin reconectar el agente, con efecto en su próxima llamada.
- Revocar un agente o todos a la vez, al instante.
- Saber de antemano qué puede editar o borrar el agente en un proyecto, y por qué no.

## ¿Cuándo conviene usarlo?

- Al conectar un agente nuevo: empezar con el alcance mínimo y en solo lectura si solo tiene que diagnosticar.
- Cuando un agente va a trabajar sobre un solo VPS o un solo proyecto.
- Si se sospecha que una credencial se filtró: revocar.

## ¿Cómo funciona en ArduMaker?

Un permiso de un agente es la suma de tres capas. Las tres terminan en «no», pero el motivo es distinto y la respuesta lo dice:

| Capa | Qué decide | Motivo que devuelve |
| --- | --- | --- |
| La persona que autorizó | El agente actúa como esa persona: rol en la empresa, en cada proyecto y acceso a cada VPS (incluidas las listas de miembros permitidos y excluidos del VPS) | `the human who authorized this agent is not an admin of this project` |
| La sesión | El alcance elegido al aprobar: proyectos, VPS y solo lectura | `this agent was authorized with read-only scope` |
| Las reglas del MCP | Operaciones que ningún agente puede hacer, tenga el alcance que tenga | `no MCP agent can ever do this, whatever its scope` |

### Alcance

- Al aprobar se elige «todos los proyectos» o una lista, y por separado «todos los VPS» o una lista. Cada id se valida contra lo que la persona puede ver: no se puede dar a un agente más acceso que el propio.
- El alcance no queda congelado en el token: se resuelve en vivo en cada llamada. Reducirlo desde `/me` vale en la llamada siguiente.
- Un alcance restringido sin ningún id no se acepta: para dejar a un agente sin acceso se lo revoca.

### Solo lectura

- El listado de herramientas solo incluye las que declaran que solo leen.
- Si igual llama a una que escribe, la llamada se rechaza con `sin_permiso` y `reintentable: false`, y queda registrada como rechazo.
- La misma regla vale para lo que el agente pueda tocar por la API REST (terminales, Docker): un agente de solo lectura no modifica un VPS por ningún camino.
- Al quitar el solo lectura, las herramientas de escritura funcionan enseguida; un cliente que ya tenía la lista cargada puede necesitar recargarla.

### Lo que ningún agente puede hacer

- Borrar un proyecto completo.
- Agregar o quitar miembros de un proyecto, o cambiar su rol.
- Crear, editar o borrar un adjunto marcado como secreto (leerlo sí, si la persona puede).
- Borrar un VPS completo.
- Crear, editar o borrar roles de un proyecto, o cambiar quién tiene qué permisos.
- Crear, editar o firmar las políticas de un proyecto.
- Leer o tocar las finanzas de un proyecto: presupuestos, pagos de clientes, lo que cobra cada colaborador y sus comprobantes.
- Enviar mensajes de WhatsApp a números reales (solo el sandbox).

## ¿Qué cambia realmente?

- La conexión guarda el alcance (`alcance_todos`, `proyectos_permitidos`, `alcance_todos_vps`, `vps_permitidos`) y `solo_lectura`.
- Revocar marca la conexión como revocada y corta también la cadena de refresh tokens: el agente pierde acceso al instante y no puede renovarse.
- Cerrar todas las sesiones revoca todos los agentes de la persona.

## Guardas y herramientas restringidas

Algunas operaciones están permitidas pero piden una confirmación en el argumento, para que quede claro qué se destruye:

| Operación | Guarda |
| --- | --- |
| Registro DNS crítico (MX, NS, A/AAAA en el apex) | `confirmado=true`; sin él, 409 |
| Borrar un usuario Linux | `confirmacion` con el nombre exacto; `root` nunca |
| Comando con forma destructiva (`rm -rf`, `mkfs`, `shutdown`, `DROP DATABASE`…) | 409 con lo que coincidió; reenviar con `confirmado=true`. Es una guarda contra accidentes, no una frontera de seguridad |
| `userdel` o `deluser` por shell | Rechazado siempre: el camino es `eliminar_usuario_vps` |
| Borrar un servicio systemd crítico | Nombres protegidos (`ssh`, `nginx`, `docker`, `mysql`, `postgresql`…) |

Hay además herramientas solo para administradores del sistema (bandeja interna de bugs y solicitudes de escuelas). Solo aparecen si quien autorizó es admin del sistema, y eso se consulta en vivo en cada llamada: si se le quita el rol, su agente lo pierde al instante.

## Esquema

**¿Puede el agente hacer esto?**

```text
¿Existe por MCP? (si no: `nunca permitido`)
  ↓
¿La sesión es de solo lectura? (si escribe: rechazo)
  ↓
¿Está en el alcance? (proyecto y VPS permitidos)
  ↓
¿Puede la persona? (rol de empresa, proyecto y VPS)
  ↓
¿Pide confirmación? (`confirmado` / `confirmacion`)
```

## Resultado esperado

- `ver_contexto_inicial` devuelve el alcance (`solo_lectura`, `todos_los_proyectos`, `todos_los_vps`) y `nunca_permitido`.
- Al ver un proyecto o una tarea, la respuesta incluye un bloque de permisos con `editar`, `borrar` y, si algo está en `false`, el `motivo`.
- En `/me` cada conexión muestra su alcance, si está activa y si se detectó reutilización de un token (`reuse_detected_at`).

## Errores y resolución

| Respuesta | Causa | Qué hacer |
| --- | --- | --- |
| `sin_permiso` por solo lectura | La sesión no escribe | Avisar a la persona: lo quita en `/me`; reintentar no sirve |
| `sin_permiso` (403) | La persona no tiene ese permiso, o el recurso está fuera del alcance | Pedir el permiso o ampliar el alcance |
| `sin_permiso` (430) | Herramienta de admin del sistema y quien autorizó no lo es | No hay camino |
| `conflicto` (409) | Falta la confirmación de una guarda | Revisar y reenviar con la confirmación |
| PATCH 400 en `/me` | Campo desconocido, tipo inválido o alcance restringido sin ids | Corregir el pedido |
| PATCH 409 en `/me` | La conexión está revocada | Volver a autorizar |

## Relación con MCP

El alcance se decide en la pantalla de autorización y se edita en `/me` (agentes conectados); no hay herramientas MCP para cambiar los propios permisos. Desde el agente, `ver_contexto_inicial` es la forma de conocerlos antes de planificar. Más detalle en [/mcp/docs](https://ardumaker.com/mcp/docs).

## Funciones relacionadas

- [Servidor MCP](https://ardumaker.com/docs/servidor-mcp/)
- [Auditoría de agentes](https://ardumaker.com/docs/auditoria-de-agentes/)
- [Roles y permisos](https://ardumaker.com/docs/roles-y-permisos/)
- [Sesiones y dispositivos](https://ardumaker.com/docs/sesiones-y-dispositivos/)