Permissões do agente MCP

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:

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:

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

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

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.

Funcionalidades relacionadas

• Servidor MCP
• Auditoria de agentes
• Funções e permissões
• Sessões e dispositivos