Claude Code managed settings na empresa: políticas, hooks e MCP

Claude Code managed settings na empresa: políticas, hooks e MCP

Para aplicar o Claude Code com políticas únicas em toda a empresa, use as configurações gerenciadas (managed settings): um arquivo de política instalado pela TI nas máquinas, ou entregue pelo console de administração, que tem precedência sobre as configurações de usuário e de projeto. Nele você define regras de permissão, hooks obrigatórios e quais servidores MCP são aceitos. O caminho mais seguro é começar com poucas regras, testar com um grupo pequeno e ampliar com evidência.

Principais pontos

• Configurações gerenciadas ficam acima das configurações de usuário e de projeto, então o desenvolvedor não as desfaz por conta própria.
• Permissões trabalham com três verbos: negar, perguntar e permitir. A lista de negação é a parte que mais protege.
• Hooks transformam regras de processo em verificações automáticas, e é possível restringir a execução a hooks definidos pela política.
• Servidores MCP podem ser entregues como lista fechada ou controlados por lista de permitidos e bloqueados.
• Política boa nasce pequena, é testada em um piloto e cresce com base em fricção real, não em medo.

O que são configurações gerenciadas e por que uma empresa precisa delas

O Claude Code lê configurações de vários níveis: usuário, projeto compartilhado, projeto local e, acima de todos, o nível gerenciado. Esse último existe para a organização. Quando um valor está definido ali, ele prevalece sobre o que a pessoa escreveu no próprio computador ou no repositório.

Sem esse nível, cada desenvolvedor decide sozinho o que o agente pode ler, executar e conectar. Isso funciona em uma equipe de duas pessoas. Em uma empresa com várias equipes, terceirizados e repositórios com dados de clientes (e, portanto, sujeitos à LGPD), a consequência é um conjunto de configurações impossível de auditar.

O objetivo não é travar o trabalho. É definir um piso comum: o que nunca acontece, o que sempre exige confirmação e o que está liberado. Cada equipe pode adicionar regras mais restritivas nos próprios projetos, mas não afrouxar o piso.

Uma ressalva de método: o Claude Code evolui rápido. Nomes de chaves, locais de arquivo e opções de distribuição mudam com o tempo. Trate este texto como roteiro e confirme os detalhes na documentação oficial de configurações do Claude Code antes de implantar.

Onde a política mora e como ela é entregue

A documentação descreve dois caminhos principais. O primeiro é o arquivo local de política, chamado managed-settings.json, instalado em um diretório do sistema que exige privilégio de administrador para editar. Há um local para macOS, outro para Linux e WSL, e outro para Windows. Os caminhos exatos estão na documentação, e vale copiá-los de lá em vez de memorizar.

O segundo caminho é a entrega pelo lado do servidor, pelo console de administração da conta da organização, quando o plano contratado oferece esse recurso. A vantagem é não depender de instalar arquivo máquina por máquina. A desvantagem é depender de recurso e plano, que você precisa verificar na sua conta.

Para o arquivo local, o padrão em empresas é distribuí-lo pela mesma ferramenta que já gerencia as máquinas: Intune, Jamf, Ansible, GPO ou um script de provisionamento. O arquivo deve ter dono claro, versionamento em repositório interno e revisão por pelo menos duas pessoas, porque uma linha errada afeta todos.

Pergunta prática antes de começar: quem tem autoridade para mudar a política? Se a resposta for "qualquer um da TI", defina um responsável e um processo de pedido. Política sem dono vira acúmulo de exceções.

Permissões: o que negar, perguntar e permitir

O bloco de permissões aceita três listas: negar, perguntar e permitir. A regra de ouro é que negar vence. Se uma ação está na lista de negação do nível gerenciado, nenhuma configuração abaixo dela a libera.

Comece pela negação, pensando em dano irreversível e em vazamento:

• Leitura de arquivos de segredos, como .env, chaves privadas e diretórios de credenciais.
• Comandos de rede que enviam conteúdo para fora sem revisão, como curl e wget com envio de dados.
• Operações destrutivas de sistema, como remoção recursiva em diretórios amplos.
• Escrita direta em ramos protegidos, se o seu fluxo exigir revisão por pull request.

Depois, a lista de "perguntar": ações que são legítimas, mas merecem um olhar humano, como publicar código, mexer em infraestrutura ou rodar migrações de banco. Por fim, a lista de permitidos deve ser curta e conter o que é rotineiro e seguro, como rodar a suíte de testes e o linter.

Outro ponto a avaliar é o modo que dispensa confirmações de permissão. A documentação prevê uma opção para desabilitá-lo no nível gerenciado. Em máquinas que tocam dados de clientes, faz sentido desligá-lo. Em um laboratório isolado, pode ser aceitável. Decida por ambiente, não por preferência.

Permissões são uma camada, não a defesa inteira. Para combiná-las com isolamento e tratamento de segredos, veja segurança no Claude Code para empresas: permissões, sandbox e segredos. Para o princípio por trás da lista de negação, a referência geral é o guia de autorização da OWASP: privilégio mínimo e negação por padrão para o que é sensível.

Hooks: regras de processo que rodam sempre

Hooks são comandos que o Claude Code executa em momentos definidos, como antes ou depois de usar uma ferramenta. No nível gerenciado, eles viram controles que ninguém precisa lembrar de acionar.

Usos comuns em empresas:

• Antes de uma escrita ou comando, verificar se o alvo está em um caminho proibido e bloquear caso esteja.
• Depois de editar arquivos, rodar formatação e verificação estática para manter o padrão do repositório.
• Registrar em um log interno quais ferramentas foram chamadas, para auditoria e para entender uso real.
• Detectar padrões de segredo no conteúdo antes de gravar.

A documentação também prevê uma restrição para que apenas hooks definidos pela política gerenciada sejam executados. Isso importa porque um hook é código rodando na máquina da pessoa. Se qualquer repositório puder trazer seus próprios hooks, um projeto clonado de origem duvidosa vira vetor de risco. Ao permitir só os hooks da política, você troca flexibilidade por previsibilidade, e essa troca costuma valer a pena em ambiente corporativo.

Cuidado com o excesso. Hook lento ou que falha por motivos obscuros irrita a equipe, que então procura contornos. Cada hook deve ter um objetivo claro, mensagem de erro compreensível e um responsável. Se você quer padronizar também instruções e comandos de equipe, vale olhar plugins do Claude Code para equipes, que cuidam da distribuição de padrões que não são política de segurança.

Servidores MCP: lista fechada ou lista de permitidos

Servidores MCP dão ao agente acesso a sistemas externos: banco de dados, CRM, ferramentas de tickets, repositórios. É onde o risco cresce mais rápido, porque cada servidor adiciona ferramentas e acesso a dados. Se o conceito é novo para você, a introdução ao Model Context Protocol e a documentação de MCP do Claude Code são o ponto de partida.

Existem duas abordagens documentadas para o nível gerenciado:

• Lista fechada: a TI distribui um arquivo gerenciado de servidores MCP (managed-mcp.json). Os usuários recebem exatamente aquele conjunto e a documentação indica que isso dá controle exclusivo, sem que cada pessoa adicione os seus.
• Lista de permitidos e bloqueados: a política define quais servidores podem ser usados e quais ficam proibidos, e os usuários ainda configuram o que for permitido. Bloqueio costuma prevalecer sobre permissão.

Como escolher:

• Poucos sistemas, dados sensíveis, equipe sem experiência: lista fechada.
• Muitas equipes técnicas com necessidades diferentes: lista de permitidos, com revisão de cada novo servidor.
• Servidor que escreve em sistemas de produção: exija confirmação por permissão e, se possível, credenciais de leitura apenas no primeiro momento.

Antes de aprovar qualquer servidor para a lista, audite. O texto como auditar um servidor MCP antes de instalar na empresa traz um roteiro, e configurar MCP no Claude Code: escopos local, projeto e usuário explica como os escopos se relacionam com a política.

Plano de implantação em etapas

Um roteiro que evita o erro mais comum, que é publicar uma política enorme de uma vez:

• Inventário: levante quem usa o Claude Code, em quais repositórios, com quais servidores MCP e com que tipo de dado. Sem isso, a política é chute.
• Piso mínimo: escreva um arquivo com poucas negações (segredos, comandos destrutivos), a restrição de hooks e a lista de MCP aprovada.
• Teste em máquina de homologação: confirme que cada regra bloqueia o que deveria e não bloqueia o fluxo normal. Teste também a precedência, tentando sobrescrever a regra em uma configuração de usuário.
• Piloto com um grupo pequeno: escolha uma equipe disposta a reportar fricção. Defina o que você vai observar, como pedidos de exceção e bloqueios indevidos.
• Ajuste: transforme cada exceção recorrente em decisão consciente: ampliar a política, criar um hook útil ou manter o bloqueio.
• Expansão gradual: distribua para as demais equipes com um canal de suporte e um dono da política.
• Revisão periódica: reavalie a política quando o Claude Code mudar de versão ou quando entrar um novo sistema integrado.

Cenário ilustrativo: uma empresa de software com três equipes mantém repositórios com dados de clientes. A TI publica uma política que nega a leitura de arquivos de ambiente, exige confirmação para comandos de deploy e aceita apenas dois servidores MCP, o de tickets em modo leitura e o de documentação interna. Na primeira semana do piloto, a equipe de dados pede um servidor de banco de dados. Em vez de liberar na hora, a TI audita o servidor, cria credencial somente de leitura e o adiciona à lista. A política cresceu por necessidade comprovada, não por antecipação.

Para acompanhar o piloto sem transformar a ferramenta em vigilância sobre pessoas, vale ler como medir produtividade com IA na equipe sem virar vigilância. O log de hooks deve servir para auditar a ferramenta e investigar incidentes, não para ranquear desenvolvedores.

Como o método mapear, limitar, pilotar e transferir se aplica

O método que usamos em projetos de IA se encaixa bem aqui. Mapear é o inventário de uso, repositórios, dados e integrações. Limitar é o piso de permissões, a restrição de hooks e a lista de MCP. Pilotar é a implantação em um grupo pequeno, com um critério de sucesso combinado, por exemplo "bloqueios indevidos caem e nenhum segredo é lido". Transferir é entregar a política com dono, processo de exceção e rotina de revisão, para que a empresa a mantenha sem depender de quem a escreveu.

Depois do piloto, a decisão é simples: expandir, ajustar ou parar. Parar também é um resultado válido, se o ambiente não comporta o risco.

Perguntas frequentes

As configurações gerenciadas impedem que o desenvolvedor mude as permissões? Elas têm precedência sobre as configurações de usuário e de projeto, então o desenvolvedor não consegue afrouxar o que a política definiu. Ele ainda pode adicionar regras mais restritivas no próprio nível. Teste a precedência na homologação para confirmar o comportamento na sua versão.

Preciso de um arquivo em cada máquina? Se usar o arquivo local de política, sim, e o ideal é distribuí-lo pela ferramenta de gestão de dispositivos que a empresa já tem. Se o seu plano oferecer entrega pelo console de administração, você evita essa distribuição. Verifique na documentação e na sua conta o que está disponível.

Vale bloquear todos os servidores MCP por padrão? Para ambientes com dados sensíveis, é um bom ponto de partida, desde que exista um caminho rápido para pedir e auditar novos servidores. Bloqueio total sem processo de exceção gera uso paralelo e escondido. Bloqueio com fila de aprovação curta mantém a equipe dentro da política.

A política substitui o treinamento da equipe? Não. A política limita o dano, mas as pessoas ainda decidem o que colar em um prompt e o que aceitar como resposta. Combine a configuração técnica com uma orientação curta de uso, alinhada à política de uso de IA da empresa, e revise ambas conforme a ferramenta evolui.

Fontes

• Claude Code: documentação de configurações
• Claude Code: documentação de MCP
• Model Context Protocol: introdução
• OWASP: guia de autorização