Como expor ferramentas MCP e controlar permissões em orquestrações de agentes

Orquestrar múltiplos agentes é insano até você perceber que cada um deles pode rodar qualquer ferramenta exposta no seu sistema MCP. Um agente de monitoramento que decide usar a tool de delete por conta própria é exatamente o tipo de pesadelo que ninguém quer debugar às 3 da manhã. MCP (Model Context Protocol) é um protocolo aberto padrão desenvolvido pela Anthropic para conectar sistemas de IA a fontes de dados, organizando como agentes conversam com ferramentas externos. Em 2026, o Claude Code SDK virou Claude Agent SDK justamente para refletir essa ambição maior: construir orquestrações de agentes completas, não só codificação.

O que é MCP e como ele organiza ferramentas

MCP é um protocolo aberto padrão da Anthropic para conectar sistemas de IA a fontes de dados. Pense como uma camada de abstração que padroniza como agentes conversam com ferramentas externas, em vez de cada um ter sua própria implementação customizada que vira legacy em 3 meses haha.

Todo MCP server expõe três blocos principais:

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Tools: ações que a IA pode executar. Exemplo: criar usuário, deletar registro, chamar API externa.

Resources: dados somente leitura. Exemplo: ler logs, acessar documentação, consultar estado atual.

Prompts: prompts predefinidos que a IA pode invocar. Exemplo: templates de análise, checklists de revisão.

Essa separação é importante porque você não quer que um agente de leitura de logs acidentalmente execute uma tool de delete por engano. É como dar acesso de só leitura vs acesso de escrita num banco de dados, a lógica é a mesma.

Como configurar permissões no Claude Agent SDK

1. allowedTools e disallowedTools com prefix matching

O Claude Agent SDK oferece três controles principais de permissão. O primeiro é allowedTools, uma whitelist de nomes de tools que o agente pode usar. Se você define allowedTools: [‘user.read’, ‘user.create’], o agente só consegue chamar essas duas e nada mais.

const agent = new Agent({
  allowedTools: ['database.read', 'database.create']
})

O lado oposto é disallowedTools, uma blacklist. Use com cuidado porque qualquer tool nova adicionada ao sistema fica automaticamente disponível para o agente se não estiver na lista.

Erro comum: esquecer que allowedTools/disallowedTools suportam prefix matching. Se você bloqueia ‘database.delete’, mas existe ‘database.deleteUser’, o agente ainda consegue chamar a segunda porque o match é estrito de prefixo, não de nome completo.

// Bloqueia tudo que começa com 'database.delete'
disallowedTools: ['database.delete']  // bloqueia database.delete e database.deleteUser

2. canUseTool callback dinâmico

O segundo controle é o canUseTool, um callback assíncrono que decide em tempo de execução se uma tool pode ser usada. A assinatura é canUseTool(toolName, input) => …, e você pode validar tanto o nome da tool quanto os parâmetros passados.

const agent = new Agent({
  canUseTool: async (toolName, input) => {
    // Bloqueia delete em produção
    if (toolName === 'database.delete' && input.environment === 'production') {
      return false
    }
    return true
  }
})

Isso é massa para casos onde a permissão depende do contexto. Um agente pode deletar em desenvolvimento mas não em produção, ou só pode acessar dados de um determinado cliente.

Erro comum: tentar fazer validação de permissão síncrona dentro do canUseTool. Como o callback é async, qualquer validação que chame banco de dados ou API externa precisa ser awaited. Se você esquecer o await, a validação vira sempre true.

3. Configuração via settings.json

O terceiro caminho é configurar via arquivo .claude/settings.json. Na seção permissions, você define allow (tools permitidas), deny (tools bloqueadas) e ask (comportamento padrão quando não está explícito).

{
  "permissions": {
    "allow": ["database.read", "user.create"],
    "deny": ["database.delete", "admin.*"],
    "ask": true
  }
}

O ask com true significa que toda tool não listada explicitamente em allow ou deny vai pedir aprovação manual antes de executar. É útil em desenvolvimento para entender o que seu agente está tentando fazer, mas pesado em produção.

Erro comum: configurar permissions só no projeto e esquecer que o Claude Code lê também o settings.json global do usuário. Se as permissões estão conflitando entre o global e o local, o comportamento fica imprevisível.

Implementando RBAC em orquestrações

RBAC (Role-Based Access Control) em MCP servers funciona agrupando permissões em roles e atribuindo essas roles a agentes. Em vez de configurar permissões agente por agente, você cria roles como ‘leitor’, ‘editor’, ‘admin’ e atribui a role adequada a cada tipo de agente.

const roles = {
  leitor: {
    allowedTools: ['database.read', 'logs.read'],
    disallowedTools: ['*.delete', '*.create', '*.update']
  },
  editor: {
    allowedTools: ['database.*'],
    disallowedTools: ['admin.*']
  }
}

const agenteLeitor = new Agent({ role: roles.leitor })

Isso escala muito melhor que definir permissões individualmente. Quando você precisa adicionar uma nova tool, atualiza a role e todos os agentes com aquela role herdam a mudança.

No platform.claude.com, permission policies controlam se ferramentas executadas pelo servidor (incluindo MCP toolset) rodam automaticamente ou aguardam aprovação manual. Você pode configurar policies baseadas em roles: agentes ‘leitor’ rodam tools automaticamente, enquanto agentes ‘editor’ precisam de aprovação para operações de risco.

Erro comum: criar roles muito específicas (ex: ‘leitor-de-producao-qa’) que não reutilizam. Comece com 3 a 5 roles genéricas e só crie roles específicas se houver um caso de uso muito claro que não se encaixa nas genéricas.

Problemas comuns no controle de acesso

Sintoma: agente usando tool errada ou bloqueado sem motivo aparente.

Causa: MCP não impõe identidade ou controle de acesso por padrão e requer implementação adicional. Ferramentas executam com suas permissões atribuídas sem inspeção de quem está chamando.

Solução: implementar canUseTool + RBAC em todo MCP server. O canUseTool valida identidade e contexto antes de permitir a execução, e o RBAC garante que cada tipo de agente só tenha acesso às tools necessárias para sua função.

canUseTool: async (toolName, input, agentIdentity) => {
  const role = getRoleForAgent(agentIdentity)
  const rolePermissions = roles[role]
  
  if (!rolePermissions.allowedTools.some(t => toolName.startsWith(t))) {
    return false
  }
  
  return true
}

Para prevenir, rode testes de permissão antes de colocar em produção. Crie um suite que tenta chamar cada tool com cada role diferente e verifica se o bloqueio acontece como esperado.

Quando usar cada tipo de controle

allowedTools: whitelist fixa para agentes com acesso muito restrito. Exemplo: agente que só lê logs do último dia. Simples, previsível, sem lógica dinâmica.

canUseTool: validação dinâmica para casos onde a permissão depende de parâmetros. Exemplo: agente pode deletar mas só se o registro tem mais de 30 dias (idade dos dados como fator de decisão). Mais flexível, mais complexo.

RBAC: multiagente com diferentes níveis de acesso. Exemplo: sistema com 10 agentes, 3 roles (leitor, editor, admin). Escala bem, centraliza a configuração.

Policies: aprovação humana para operações de risco. Exemplo: agente sugere delete mas só executa após humano aprovar. Adiciona fricção proposital para operações críticas.

No vídeo abaixo eu mostro o DevTools MCP na prática com o Chrome 144, testei num projeto de encurtador de URL em localhost. A configuração de permissões fez toda diferença: a IA preencheu formulário, criou conta, detectou email já cadastrado, fez CRUD completo de links e até implementou uma nova funcionalidade de configurações de aleatoriedade. Mas quando a extensão está ativa, aparece indicador de que o Chrome está sendo controlado por software de teste automatizado. Elementos nativos do navegador como confirmações deram problema, mas a navegação programática pela DOM funcionou muito bem.

O ganho de tempo vem de poder testar a partir de uma sessão já aberta, sem precisar refazer login inteiro. Recomendo para testes mais milimétricos ao entrar num ponto específico da aplicação.

Conclusão

Controle de acesso em orquestração de agentes MCP não é algo para deixar pra depois. Comece implementando canUseTool no seu primeiro agente e teste com tools de risco antes de colocar em produção. Use RBAC assim que você tiver mais de 3 agentes com níveis de acesso diferentes. E lembre: MCP não impõe identidade por padrão, você tem que implementar. Cada tool exposta é uma superfície de ataque, e cada agente é um potencial usuário mal intencionado que não sabe que está fazendo algo errado haha.

Próximo passo: implemente canUseTool no seu primeiro agente e rode testes tentando chamar tools bloqueadas. Se o agente tentar e falhar com erro claro, sua camada de segurança está funcionando.