Como definir permissões de plugin de agente de terceiros

O pacote chega lacrado, com o conector exposto. O manifesto que vem dentro tem dez campos e nenhum deles declara permissão portátil.

A comparação que ajuda é de instalação elétrica: você compra o aparelho, não o disjuntor. O limite entra depois, na parede, por decisão de quem instala. Com plugin de agente a lógica se repete, e a decisão continua sendo de quem instala, não do arquivo que chegou.

Em 6 de agosto de 2026, a especificação Agent Plugins 1.0.0 padronizou o pacote de skills e servidores MCP, com manifesto de dez campos e nenhuma permissão portátil. Definir permissões de plugin de agente exige decidir, antes da instalação, quais componentes aceitar, qual credencial usar e quais escopos aprovar.

Quadro de decisão / Fatos-chave: Módulo selado, conector exposto: nenhum dos dez campos traz permissão portátil [3][4]. Só $schema e name são obrigatórios; version é opcional [4]. allowed-tools é opcional, experimental e de suporte variável [10]. Se o desafio traz scope, ele é autoritativo; sem ele, a recomendação é pedir todos os escopos de scopes_supported, se definido [12].

Pré-requisitos

Antes do primeiro passo, o time precisa de acesso administrativo ao cliente, lista de plugins aprovados, cofre de credencial fora do pacote e destino para o inventário. Sem acesso ao cliente, não há como conferir o que foi carregado. Sem inventário, não há como provar a decisão.

Cada cliente de Agent Plugins controla instalação e permissões [2]. A lista de clientes compatíveis trazia doze, contra cinco no anúncio [1][8]. Isso não mede maturidade. Antes de instalar um plugin de terceiro, a equipe precisa identificar o cliente usado e conferir os componentes que ele efetivamente carrega. O manifesto não fornece uma permissão portátil: a revisão alcança skills, servidores MCP e as credenciais que cada servidor recebe [3][4]. Em cabeçalho literal, o formato proíbe segredo, mas não impede sua inclusão no pacote [16]. O cofre fica fora dele. No servidor remoto, a aprovação também exige examinar o emissor e comparar o escopo solicitado com a política [12][13]. O registro posterior distingue a decisão de aceite do resultado da conexão, pois uma falha pode deixar apenas parte do pacote ativa [5]. Descoberta e versionamento de servidores em escala é outro trabalho.

Seis passos, na ordem em que a decisão acontece:

1. Verificar o plugin.json como identidade.
2. Separar skills de servidores MCP.
3. Decidir o aceite por componente.
4. Decidir a credencial que o servidor recebe.
5. Ler o escopo no desafio de autorização.
6. Instalar e registrar o inventário ativo.

Passo 1: o manifesto é identidade, não é contrato de permissão

No plugin.json, são aceitos dez campos de topo, com apenas $schema e name obrigatórios. Nenhum define permissão portátil. Campo desconhecido e extensions que não seja objeto são reportados e ignorados, com carga continuada; as demais violações de esquema são fatais, e o cliente rejeita o plugin sem descobrir nem executar seus componentes [3][4].

Os demais campos do manifesto plugin.json são version, description, author, homepage, repository, license, keywords e extensions; version ausente não impede a instalação [4]. Nome e versão identificam o pacote, enquanto extensions pode conter dados específicos de um cliente. O manifesto não define uma permissão portátil. "permissions": [...] no topo do manifesto de plugin é violação de esquema: o cliente conforme reporta e ignora o campo, sem lhe atribuir semântica [3][4]. O rótulo não vincula ninguém. A diferença está no resultado: o pacote continua com campo desconhecido, mas um name de tipo errado leva à rejeição antes da descoberta. A especificação recomenda que o cliente identifique o campo obrigatório inválido [4]. Se extensions não for objeto, o campo é reportado e ignorado, sem interromper a carga [3]. Dentro de um namespace implementado, a validação segue as regras do cliente; namespaces não implementados são ignorados [4].

O manifesto identifica o que foi baixado. Não responde o que o plugin pode fazer.

Passo 2: separar os dois tipos de componente

A versão 1 padroniza skills, instruções carregadas no contexto, e servidores MCP, processos locais ou conexões remotas declaradas no mcp.json do plugin. Esse arquivo define o transporte e a configuração do servidor. Comandos, hooks e agentes ficam com cada cliente, fora do núcleo portável [1][3][9]. O aceite começa na separação.

Uma skill de plugin não é chamada de ferramenta: é instrução carregada no contexto quando o descritor casa com a tarefa [11], descoberta em diretório fixo e validada individualmente [7]. O campo allowed-tools é opcional, experimental e de suporte variável [10]. Não é um limite garantido. Aceitar uma skill de terceiro é aceitar conteúdo não confiável que pode influenciar o modelo com as ferramentas já concedidas ao agente. Seu teto efetivo é o ferramental exposto pelo host: revisar a skill exige examinar instruções e risco de injeção, não só o esquema [7][10][11]. No topo do mcp.json, só são aceitos $schema e mcpServers. Stdio exige type e command, com args, env e cwd opcionais; remoto exige type e url, com cabeçalhos literais opcionais. sse está obsoleto, com suporte opcional [16]. Comando e argumentos vêm do autor.

Hooks cabem no diretório de extensão do cliente [1][3]. Segundo o VS Code, hooks e servidores MCP podem executar código na máquina [14].

Passo 3: permissões de plugin de agente decididas por componente

Permissões de plugin de agente exigem decisão por componente: entrada de servidor inválida desabilita só aquela entrada, skill inválida não derruba os outros tipos, e falha de autenticação é falha de conexão [5][6]. Há uma exceção: mcp.json inválido no topo desabilita todo o MCP do plugin [16].

Um plugin de agente reúne superfícies com limites diferentes. Na skill, allowed-tools depende do cliente e não garante contenção das instruções [10]. No servidor MCP stdio, command, args, env e cwd configuram a partida do processo, mas a contenção de caminho governa arquivos do pacote: não isola o subprocesso nem restringe caminhos de execução [3][9]. No servidor MCP remoto, o escopo do desafio orienta a autorização; se faltar, há fallback para scopes_supported, quando definido, e a concessão pode diferir do pedido [12][13]. O autor declara componentes e configurações; sua aplicação depende do cliente [2]. Uma entrada inválida de servidor é ignorada sem derrubar os demais componentes, enquanto um mcp.json inválido no topo desabilita todo o MCP do plugin [5][6][16]. A recusa seletiva de uma entrada válida depende das opções do cliente, não é uma garantia da especificação. A tabela separa os limites:

A última coluna decide. allowed-tools depende do cliente [10]. A contenção de caminho governa arquivos do pacote, mas não isola o subprocesso nem restringe caminhos de execução [3][9]. No remoto, o escopo pode faltar e a concessão pode diferir do pedido [12][13]. O autor declara componentes e configurações; sua aplicação depende do cliente [2].

Permissão mínima de agente em produção: token efêmero trata da tarefa; aqui a unidade é o componente.

Passo 4: decidir a credencial que o servidor recebe

Em stdio, a especificação recomenda obter credenciais do ambiente e não seguir o fluxo de autorização do MCP [12]. Uma entrada cujo env declara PLUGIN_ROOT ou PLUGIN_DATA é inválida e rejeitada; no ambiente do processo lançado, o cliente define essas variáveis por último [5][16]. Vale comparar as demais variáveis antes do aceite.

Quem configura o ambiente base decide a identidade apenas nas variáveis não declaradas pelo pacote. Uma colisão pode trocar a credencial usada. Os nomes de env e do ambiente base precisam ser comparados antes do aceite. Em um servidor MCP stdio válido, o cliente aplica o env do pacote sobre o ambiente base e define por último PLUGIN_ROOT e PLUGIN_DATA no ambiente lançado [5][16]. A regra não torna válida uma entrada cujo env declare esses nomes reservados: o cliente deve rejeitar a entrada e continuar carregando os demais componentes [3][5]. Cabeçalho configurado no mcp.json é dado literal e visível do pacote, e não deve conter credencial nem segredo [16]. A especificação proíbe, mas não bloqueia tecnicamente. Um token colado ali viaja com o pacote. Quando o servidor remoto usa autorização, o cliente descobre o servidor de autorização pelo metadado de recurso protegido. A credencial é gerida pelo lado do cliente [5].

Credencial de agente em produção: o problema do espalhamento trata do inventário de credenciais.

Passo 5: ler o escopo no desafio antes de aprovar

O servidor deve incluir scope no WWW-Authenticate, mas pode omiti-lo: é uma recomendação, não uma garantia. Se presente, o escopo desafiado é autoritativo para a operação. Sem ele, o cliente é orientado a pedir todos os escopos de scopes_supported, quando definido [12]. Antes do escopo, cabe conferir o emissor.

Na autorização de um servidor MCP remoto, o scope do desafio é autoritativo para a operação quando presente. Não há relação presumida entre os escopos do desafio e scopes_supported: o desafio pode conter escopos fora da lista [12]. Se nenhum dos dois estiver disponível, a orientação é omitir scope no pedido [12]. A concessão pode ser menor [13]. Cabe a quem aprova comparar pedido e concessão com a política, inclusive no fallback. A URL resource_metadata no desafio e as URLs authorization_servers no metadado podem ser controladas pelo servidor de terceiro [13]. Validar a origem e o emissor esperado reduz o risco de consentir em um servidor de autorização alheio; as URLs também exigem proteção contra SSRF. O cliente deve enviar resource, com a URI canônica do servidor MCP pretendido, nas requisições de autorização e de token, mesmo que o servidor de autorização não o suporte [12]. O servidor MCP deve validar a audiência e não aceitar token emitido para outro destino.

Token passthrough é proibido pelas práticas de segurança do MCP [13]. O repasse pode dificultar a auditoria; o cumprimento da proibição depende do servidor aceito.

Passo 6: instalar e registrar o inventário que ficou ativo

Se um servidor falha ao iniciar, conectar, autenticar ou completar o handshake, o cliente continua carregando os outros servidores e componentes [5], sem tratar a falha como configuração inválida. A instalação pode parecer concluída com um servidor fora. Registrar o resultado revela qual subconjunto ficou ativo.

O inventário de um plugin de agente precisa distinguir configuração, conexão e execução. Por componente, o registro guarda tipo, origem, credencial, resultado da conexão, data e versão do cliente. Uma entrada de servidor MCP inválida é ignorada individualmente; uma falha de autenticação, por sua vez, é tratada como falha de conexão [5][6]. São resultados distintos. Se a configuração no topo de mcp.json for inválida, todo o MCP do plugin fica desabilitado, embora o cliente continue carregando outros tipos de componente [16]. A especificação não define fallback após a primeira falha de conexão [16]. Por isso, o transporte declarado e o resultado da tentativa precisam aparecer no inventário, em vez de serem presumidos pelo aceite inicial. A lista não isola o subprocesso [3][9]. Depois da carga, a comparação entre os componentes aceitos e os efetivamente ativos indica o que ficou disponível para a política de tarefa.

O limite de taxa por operação MCP é outra decisão, após a carga da ferramenta.

Como verificar que a permissão em uso é a que foi decidida

Três checagens fecham a verificação após a instalação: listar componentes carregados, comparar o escopo concedido com o decidido e registrar cada chamada com sujeito, ferramenta e resultado. A primeira mostra o que ficou de fora; a segunda encontra concessões maiores que a política previa.

Verificar permissões de plugin de agente exige inventário, escopo e log, nessa ordem. O inventário registra tipo, origem, credencial, conexão, data e versão do cliente; a comparação com o aceite revela componentes que não carregaram [5][16]. Para o servidor MCP remoto, o escopo do desafio é autoritativo para a operação quando presente, mas a concessão pode ser menor que o pedido [12][13]. Conferir os dois conjuntos evita tratar o pedido como prova da permissão efetiva. O registro de cada chamada associa sujeito, ferramenta e resultado à atividade observada. Nenhuma dessas checagens transforma a contenção de arquivos em sandbox: a especificação não isola o subprocesso nem restringe seus caminhos de execução [3][9]. A matriz de menor privilégio e a trilha ficam em Permissões e acesso de agentes de IA: defina e rastreie. A política de tarefa é uma decisão separada do aceite do componente.

O pacote continua válido.

Erros que se repetem

Quatro erros se repetem: confundir validação com sandbox, aprovar o pacote como decisão única, estender a confiança do marketplace ao plugin e supor que falha de autenticação desinstala o resto. Nenhum costuma aparecer no log como erro, e é por isso que dura. Se você só olha falha de execução, os quatro passam.

No plugin de agente, esquema e contenção descrevem o pacote, não impõem sandbox [3]. A validação de caminhos de arquivos não restringe os caminhos de execução de um subprocesso depois que ele inicia [3][9]. O aceite único também esconde o subconjunto ativo [5][16]. Uma falha de conexão de servidor MCP não reverte o pacote: o cliente continua carregando outros servidores e componentes [5]. Uma entrada inválida e um mcp.json inválido no topo também produzem resultados diferentes, respectivamente a rejeição da entrada e a desabilitação do MCP do plugin [5][16]. Já a confiança no marketplace não cobre automaticamente a do plugin: o VS Code pede revisão do publicador e confiança no primeiro plugin de cada marketplace [14]. O manifesto tampouco substitui a decisão de permissão: nenhum dos dez campos de topo define autorização portátil [3][4]. Para o servidor remoto, a aprovação precisa incluir emissor e escopo, inclusive quando o desafio não informa scope [12][13].

Permissões de plugin de agente exigem decisões além do rótulo. Controle de modelo em agentes de IA em produção trata de outra camada.

Perguntas frequentes

O manifesto de um plugin de agente não oferece permissão portátil. Dados em extensions dependem do cliente; a rejeição de servidor inválido não garante recusa seletiva de uma entrada válida. Na autorização remota, o desafio orienta o pedido. Validação do pacote e isolamento de execução são decisões diferentes [3][4][5][12].

Na especificação Agent Plugins 1.0.0, extensions pode carregar dados específicos de um namespace implementado pelo cliente, mas não estabelece uma permissão portátil [4]. Uma entrada de servidor MCP inválida é ignorada enquanto os demais componentes continuam carregando; a opção de recusar seletivamente uma entrada válida depende do cliente [5][6]. Na autorização MCP remota, o scope presente no desafio é autoritativo para a operação. Sem scope, a orientação é pedir todos os escopos de scopes_supported, quando definido, ou omitir o parâmetro se nenhum estiver disponível [12]. A concessão pode ser menor [13]. Um cabeçalho literal de mcp.json não deve conter credenciais nem segredos, embora o formato não impeça sua inclusão [16]. A validação de caminhos protege a leitura de arquivos do pacote, mas não oferece sandbox nem limita os caminhos acessíveis pelo subprocesso em execução [3][9].

O campo extensions pode carregar uma permissão?

Pode carregar semântica de permissão específica, mas não uma permissão portátil. Em extensions, o dono do namespace define o conteúdo e sua validação; o cliente que implementa esse namespace pode aplicá-lo [4]. A documentação do cliente instalado define essa semântica; namespaces que ele não implementa são ignorados.

Dá para aceitar só as skills e recusar o servidor MCP?

É possível se o cliente oferecer recusa seletiva de um servidor válido; a especificação não garante essa opção. Em caso diferente, uma entrada inválida é ignorada e o cliente continua carregando os outros componentes, inclusive skills suportadas [5][6]. Mas um mcp.json inválido no topo desabilita o MCP do plugin inteiro [16].

Quem aprova o escopo quando o servidor MCP é de terceiro?

Quem instala, conforme a política da organização. Se o desafio traz scope, ele é autoritativo para a operação, sem relação presumida com scopes_supported [12]. Se não traz, o cliente é orientado a pedir todos os escopos anunciados, quando disponíveis. Pedido e emissor precisam ser revistos antes da aprovação.

O mcp.json pode carregar credencial em cabeçalho?

Não deve. Cabeçalho configurado no mcp.json é visível para quem instala e não pode conter credencial nem segredo [16]. A proibição é normativa, não técnica: nada no formato impede um autor de colar um token ali, e o token viaja com o pacote.

A validação do pacote isola o que o plugin executa?

Não. O que a validação entrega é uma descrição do pacote, não uma fronteira para o processo [3], e sandbox de execução é escolha do cliente, que o formato não impõe: depois que o servidor sobe, o que ele alcança não depende do esquema.

Referências e Leitura Complementar

As fontes primárias separam o formato do plugin, o comportamento do cliente e a autorização MCP. A especificação Agent Plugins 1.0.0 define manifesto e carga; a especificação MCP define a seleção de escopo para autorização remota. A documentação do cliente registra comportamentos específicos que não são portáveis [3][4][12][14].

A especificação Agent Plugins 1.0.0 descreve o manifesto fechado, os dois tipos de componente e os limites de falha durante a carga [3]. A referência do manifesto detalha extensions e os campos aceitos [4]; a documentação de servidores MCP cobre mcp.json, transportes e configuração [16]. A especificação Agent Skills descreve allowed-tools, enquanto a página de skills do plugin trata da descoberta [7][10]. A autorização MCP estabelece a prioridade entre o scope do desafio e scopes_supported [12]. As práticas de segurança MCP abordam audiência, emissor e token passthrough [13]. A documentação do VS Code descreve a revisão do publicador e a confiança no primeiro plugin de cada marketplace, uma regra daquele cliente [14]. A lista de clientes compatíveis e o anúncio fornecem as duas contagens citadas, sem medir maturidade [1][8]. O material também distingue falhas de conexão de configurações inválidas [5][6].

Fontes consultadas em 13 de novembro de 2026.

1. Vercel, Introducing Agent Plugins, publicado em 6 de agosto de 2026.
2. Agent Plugins, página inicial da especificação.
3. Agent Plugins, Specification 1.0.0.
4. Agent Plugins, Plugin manifest.
5. Agent Plugins, MCP runtime.
6. Agent Plugins, Client conformance checklist.
7. Agent Plugins, Skills.
8. Agent Plugins, Compatible Clients.
9. Repositório da especificação, agent-plugins-spec.
10. Agent Skills, Specification.
11. Agent Skills, página inicial.
12. Model Context Protocol, Specification 2026-07-28, Authorization.
13. Model Context Protocol, Security Best Practices.
14. Visual Studio Code Docs, Agent plugins in VS Code.
15. GitHub Docs, Plugins for GitHub Copilot.
16. Agent Plugins, MCP servers.

O que fazer com o primeiro pacote aceito

Com o inventário em mãos, cada ferramenta aceita precisa de uma política de tarefa. Componente, credencial e escopo decidem o que entra; a política decide o que a ferramenta pode fazer depois. São decisões separadas, com registros para comparação posterior.

O Nexforce Agents inclui o Nexforce Work para times não técnicos, com aprovações, sandbox, gestor de skills e conectores MCP, e o Nexforce Code para terminal, IDE e CI. Nos dois, o Nexforce Router é a camada de inferência. Nenhum material público consultado documenta escopo por plugin ou emissão de credencial por componente nesses produtos. A especificação Agent Plugins 1.0.0 tampouco define permissão portátil no manifesto [3][4]. A equipe deve conferir no cliente instalado quais componentes foram carregados e comparar o resultado com o inventário de aceite. Para o servidor MCP remoto, o escopo solicitado e o efetivamente concedido precisam ser comparados à política, pois a concessão pode ser menor [12][13]. A lista de componentes não substitui isolamento de processo: as regras de contenção do pacote não são sandbox [3][9]. Depois do aceite, a política de tarefa e o registro de sujeito, ferramenta e resultado tratam da utilização das ferramentas.

O pacote chega com identidade. A permissão continua sendo sua.