MCP agent permissions

What an MCP agent can do: its human's permissions, scope by project and VPS, read-only mode and operations that are always forbidden.

Category: AI and agents
Status: Available
Requirements: An ArduMaker account that authorizes the agent; An agent connected to the MCP server (see MCP server)
MCP tools (Read only): ver_contexto_inicial

Markdown

What can you do with it?

Restrict an agent to certain projects and, separately, to certain VPS.
Keep an agent read-only: it neither sees nor can call tools that modify data.
Change the scope or mode from /me without reconnecting the agent, effective on its next call.
Revoke one agent or all of them at once, instantly.
Know in advance what the agent can edit or delete in a project, and why not.

When should you use it?

When connecting a new agent: start with the minimum scope, and read-only if it only has to diagnose.
When an agent is going to work on a single VPS or a single project.
If you suspect a credential leaked: revoke.

How does it work in ArduMaker?

An agent's permission is the sum of three layers. All three end in “no”, but the reason differs and the answer says which:

Layer	What it decides	Reason returned
The person who authorized	The agent acts as that person: role in the company, in each project and access to each VPS (including the VPS allowed and excluded member lists)	`the human who authorized this agent is not an admin of this project`
The session	The scope chosen when approving: projects, VPS and read-only	`this agent was authorized with read-only scope`
MCP rules	Operations no agent can perform, whatever its scope	`no MCP agent can ever do this, whatever its scope`

Scope

When approving, choose “all projects” or a list, and separately “all VPS” or a list. Each id is validated against what the person can see: an agent cannot get more access than its human.
The scope is not frozen in the token: it is resolved live on every call. Reducing it from /me applies to the next call.
A restricted scope with no ids is not accepted: to leave an agent without access, revoke it.

Read-only

The tool list only includes those that declare they only read.
If it still calls one that writes, the call is rejected with sin_permiso and reintentable: false, and recorded as a rejection.
The same rule applies to what the agent could touch through the REST API (terminals, Docker): a read-only agent does not modify a VPS by any path.
When read-only is turned off, write tools work right away; a client that already loaded the list may need to reload it.

What no agent can do

Delete a whole project.
Add or remove project members, or change their role.
Create, edit or delete an attachment marked as secret (reading it is allowed if the person can).
Delete a whole VPS.
Create, edit or delete project roles, or change who has which permissions.
Create, edit or sign a project's policies.
Read or touch a project's finances: budgets, client payments, what each collaborator is paid and their receipts.
Send WhatsApp messages to real numbers (sandbox only).

What actually changes?

The connection stores the scope (alcance_todos, proyectos_permitidos, alcance_todos_vps, vps_permitidos) and solo_lectura.
Revoking marks the connection as revoked and also cuts the refresh token chain: the agent loses access instantly and cannot renew.
Closing all sessions revokes every agent of the person.

Guards and restricted tools

Some operations are allowed but require a confirmation in the arguments, so it is clear what is being destroyed:

Operation	Guard
Critical DNS record (MX, NS, A/AAAA at the apex)	`confirmado=true`; without it, 409
Delete a Linux user	`confirmacion` with the exact name; never `root`
Command with a destructive shape (`rm -rf`, `mkfs`, `shutdown`, `DROP DATABASE`…)	409 with what matched; resend with `confirmado=true`. It guards against accidents, it is not a security boundary
`userdel` or `deluser` through the shell	Always rejected: the path is `eliminar_usuario_vps`
Delete a critical systemd service	Protected names (`ssh`, `nginx`, `docker`, `mysql`, `postgresql`…)

There are also tools only for system administrators (internal bug inbox and school requests). They only show up if whoever authorized is a system admin, and that is checked live on every call: if the role is removed, the agent loses it instantly.

Diagram

Does it exist over MCP?: if not: never allowed
Is the session read-only?: if it writes: rejection
Is it in scope?: allowed project and VPS
Can the person?: company, project and VPS role
Does it require confirmation?: confirmado / confirmacion

Can the agent do this?

Expected result

ver_contexto_inicial returns the scope (solo_lectura, todos_los_proyectos, todos_los_vps) and nunca_permitido.
When viewing a project or task, the answer includes a permissions block with editar, borrar and, if something is false, the motivo.
In /me each connection shows its scope, whether it is active and whether token reuse was detected (reuse_detected_at).

Errors and troubleshooting

Answer	Cause	What to do
`sin_permiso` because of read-only	The session does not write	Tell the person: they turn it off in `/me`; retrying does not help
`sin_permiso` (403)	The person lacks that permission, or the resource is out of scope	Ask for the permission or widen the scope
`sin_permiso` (430)	System admin tool and whoever authorized is not one	There is no path
`conflicto` (409)	A guard's confirmation is missing	Review and resend with the confirmation
PATCH 400 in `/me`	Unknown field, invalid type or restricted scope with no ids	Fix the request
PATCH 409 in `/me`	The connection is revoked	Authorize again

MCP access

The scope is decided on the authorization screen and edited in /me (connected agents); there are no MCP tools to change the agent's own permissions. From the agent, ver_contexto_inicial is the way to know them before planning. More detail at /mcp/docs.