# Permissões do agente MCP

O que pode fazer um agente MCP: permissões do seu humano, alcance por projeto e VPS, só leitura e operações sempre proibidas.

Fonte: https://ardumaker.com/pt/docs/permisos-mcp/

- Categoria: Inteligência artificial e agentes
- Estado: Disponível
- Requisitos: Uma conta ArduMaker que autoriza o agente; Um agente ligado ao servidor MCP (ver [Servidor MCP](https://ardumaker.com/pt/docs/servidor-mcp))
- Ferramentas MCP (Só leem): `ver_contexto_inicial`

## O que permite fazer?

- Limitar um agente a certos projetos e, em separado, a certos VPS.
- Deixar um agente em só leitura: não vê nem pode chamar ferramentas que modificam dados.
- Mudar o alcance ou o modo a partir de `/me` sem voltar a ligar o agente, com efeito na sua próxima chamada.
- Revogar um agente ou todos de uma vez, no momento.
- Saber antecipadamente o que o agente pode editar ou apagar em um projeto, e porque não.

## Quando convém usar?

- Ao ligar um agente novo: começar com o alcance mínimo e em só leitura se só tiver de diagnosticar.
- Quando um agente vai trabalhar sobre um único VPS ou um único projeto.
- Se se suspeitar que uma credencial foi divulgada: revogar.

## Como funciona na ArduMaker?

Uma permissão de um agente é a soma de três camadas. As três terminam em “não”, mas o motivo é diferente e a resposta di-lo:

| Camada | O que decide | Motivo devolvido |
| --- | --- | --- |
| A pessoa que autorizou | O agente age como essa pessoa: papel na empresa, em cada projeto e acesso a cada VPS (incluindo as listas de membros permitidos e excluídos do VPS) | `the human who authorized this agent is not an admin of this project` |
| A sessão | O alcance escolhido ao aprovar: projetos, VPS e só leitura | `this agent was authorized with read-only scope` |
| As regras do MCP | Operações que nenhum agente pode fazer, tenha o alcance que tiver | `no MCP agent can ever do this, whatever its scope` |

### Alcance

- Ao aprovar escolhe-se “todos os projetos” ou uma lista, e em separado “todos os VPS” ou uma lista. Cada id é validado contra o que a pessoa pode ver: não é possível dar a um agente mais acesso que o próprio.
- O alcance não fica congelado no token: é resolvido em tempo real em cada chamada. Reduzi-lo a partir de `/me` vale na chamada seguinte.
- Um alcance restrito sem nenhum id não é aceito: para deixar um agente sem acesso, revoga-se.

### Só leitura

- A lista de ferramentas só inclui as que declaram que só leem.
- Se mesmo assim chamar uma que escreve, a chamada é rejeitada com `sin_permiso` e `reintentable: false`, e fica registrada como rejeição.
- A mesma regra vale para o que o agente possa tocar pela API REST (terminais, Docker): um agente só de leitura não modifica um VPS por nenhum caminho.
- Ao tirar o só leitura, as ferramentas de escrita funcionam logo; um cliente que já tinha a lista carregada pode precisar de a recarregar.

### O que nenhum agente pode fazer

- Apagar um projeto completo.
- Acrescentar ou retirar membros de um projeto, ou mudar o seu papel.
- Criar, editar ou apagar um anexo marcado como secreto (lê-lo sim, se a pessoa puder).
- Apagar um VPS completo.
- Criar, editar ou apagar papéis de um projeto, ou mudar quem tem que permissões.
- Criar, editar ou assinar as políticas de um projeto.
- Ler ou tocar nas finanças de um projeto: orçamentos, pagamentos de clientes, o que recebe cada colaborador e os seus comprovativos.
- Enviar mensagens de WhatsApp para números reais (só o sandbox).

## O que muda realmente?

- A link guarda o alcance (`alcance_todos`, `proyectos_permitidos`, `alcance_todos_vps`, `vps_permitidos`) e `solo_lectura`.
- Revogar marca a link como revogada e corta também a cadeia de refresh tokens: o agente perde acesso no momento e não se pode renovar.
- Fechar todas as sessões revoga todos os agentes da pessoa.

## Proteções e ferramentas restritas

Algumas operações são permitidas mas pedem uma confirmação no argumento, para que fique claro o que se destrói:

| Operação | Proteção |
| --- | --- |
| Registro DNS crítico (MX, NS, A/AAAA no apex) | `confirmado=true`; sem ele, 409 |
| Apagar um usuário Linux | `confirmacion` com o nome exato; nunca `root` |
| Comando com forma destrutiva (`rm -rf`, `mkfs`, `shutdown`, `DROP DATABASE`…) | 409 com o que coincidiu; reenviar com `confirmado=true`. É uma proteção contra acidentes, não uma fronteira de segurança |
| `userdel` ou `deluser` pela shell | Sempre rejeitado: o caminho é `eliminar_usuario_vps` |
| Apagar um serviço systemd crítico | Nomes protegidos (`ssh`, `nginx`, `docker`, `mysql`, `postgresql`…) |

Há ainda ferramentas só para administradores do sistema (caixa interna de bugs e pedidos de escolas). Só aparecem se quem autorizou for admin do sistema, e isso é consultado em tempo real em cada chamada: se lhe tirarem o papel, o seu agente perde-o no momento.

## Esquema

**O agente pode fazer isto?**

```text
Existe por MCP? (se não: `nunca permitido`)
  ↓
A sessão é só de leitura? (se escreve: rejeição)
  ↓
Está no alcance? (projeto e VPS permitidos)
  ↓
A pessoa pode? (papel de empresa, projeto e VPS)
  ↓
Pede confirmação? (`confirmado` / `confirmacion`)
```

## Resultado esperado

- `ver_contexto_inicial` devolve o alcance (`solo_lectura`, `todos_los_proyectos`, `todos_los_vps`) e `nunca_permitido`.
- Ao ver um projeto ou uma tarefa, a resposta inclui um bloco de permissões com `editar`, `borrar` e, se algo estiver em `false`, o `motivo`.
- Em `/me` cada link mostra o seu alcance, se está ativa e se foi detetada reutilização de um token (`reuse_detected_at`).

## Erros e resolução

| Resposta | Causa | O que fazer |
| --- | --- | --- |
| `sin_permiso` por só leitura | A sessão não escreve | Avisar a pessoa: tira-o em `/me`; repetir não serve |
| `sin_permiso` (403) | A pessoa não tem essa permissão, ou o recurso está fora do alcance | Pedir a permissão ou alargar o alcance |
| `sin_permiso` (430) | Ferramenta de admin do sistema e quem autorizou não o é | Não há caminho |
| `conflicto` (409) | Falta a confirmação de uma proteção | Rever e reenviar com a confirmação |
| PATCH 400 em `/me` | Campo desconhecido, tipo inválido ou alcance restrito sem ids | Corrigir o pedido |
| PATCH 409 em `/me` | A link está revogada | Voltar a autorizar |

## Relação com MCP

O alcance decide-se no tela de autorização e edita-se em `/me` (agentes ligados); não há ferramentas MCP para mudar as próprias permissões. A partir do agente, `ver_contexto_inicial` é a forma de as conhecer antes de planear. Mais detalhe em [/mcp/docs](https://ardumaker.com/pt/mcp/docs).

## Funcionalidades relacionadas

- [Servidor MCP](https://ardumaker.com/pt/docs/servidor-mcp/)
- [Auditoria de agentes](https://ardumaker.com/pt/docs/auditoria-de-agentes/)
- [Funções e permissões](https://ardumaker.com/pt/docs/roles-y-permisos/)
- [Sessões e dispositivos](https://ardumaker.com/pt/docs/sesiones-y-dispositivos/)