Permisos del agente MCP

¿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:

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:

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

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

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.

Funciones relacionadas

• Servidor MCP
• Auditoría de agentes
• Roles y permisos
• Sesiones y dispositivos