Configurar MCP no Claude Code: escopos local, projeto e usuário

Configurar MCP no Claude Code: escopos local, projeto e usuário

Para configurar MCP no Claude Code, você escolhe um escopo ao adicionar o servidor: local (só você, só naquele projeto), de projeto (arquivo .mcp.json versionado e compartilhado com a equipe) ou de usuário (só você, em todos os projetos). A regra prática é versionar apenas a estrutura da configuração no escopo de projeto e deixar segredos fora do repositório, usando variáveis de ambiente.

Este guia segue a documentação oficial do Claude Code sobre MCP e separa o que ela afirma do que é recomendação de implementação. Os nomes de comandos e caminhos podem mudar entre versões, então confirme na documentação atual antes de padronizar para a equipe.

Principais pontos

• O escopo local é o padrão ao adicionar um servidor: fica privado para você e vale só para o projeto em que você está.
• O escopo de projeto grava um arquivo .mcp.json na raiz do repositório, pensado para ser versionado e compartilhado.
• O escopo de usuário deixa o servidor disponível em todos os seus projetos, sem compartilhar com ninguém.
• Credenciais nunca devem ir no .mcp.json em texto puro: use expansão de variáveis de ambiente e deixe cada pessoa fornecer o próprio valor.
• Servidores de projeto pedem aprovação explícita antes de rodar, o que é uma barreira útil, não um incômodo a contornar.

O que o MCP resolve e por que o escopo importa

O Model Context Protocol é um padrão aberto para conectar aplicações de IA a ferramentas e fontes de dados externas. Na introdução oficial do MCP, a ideia é que um servidor exponha capacidades (ler um chamado, consultar um banco, abrir uma issue) e o cliente, no caso o Claude Code, as use quando a tarefa pedir.

O escopo responde a uma pergunta de gestão, não só técnica: quem vê e quem usa este acesso? Um servidor que lê o sistema de chamados interno pode ser útil para toda a equipe. Um servidor que aponta para uma conta pessoal de teste, ou que usa um token seu, não deve ir para o repositório. Errar o escopo costuma gerar dois problemas: configuração que só funciona na máquina de uma pessoa, ou credencial que acaba em um commit.

Quais são os três escopos e onde cada um fica

A documentação oficial descreve três escopos. Vale decorar o comportamento de cada um.

• Local: é o padrão. O servidor fica disponível só para você e só no projeto atual. A configuração é armazenada no arquivo ~/.claude.json, associada ao caminho do projeto. Serve para experimentos, para credenciais pessoais e para servidores sensíveis que ainda estão em avaliação.
• Projeto: o servidor é gravado em um arquivo .mcp.json na raiz do repositório. Esse arquivo foi desenhado para entrar no controle de versão, de modo que todos que clonarem o projeto recebam a mesma lista de servidores.
• Usuário: o servidor fica disponível para você em todos os projetos, também guardado no ~/.claude.json, e não é compartilhado. Serve para utilitários pessoais que você quer em qualquer lugar.

Quando o mesmo nome de servidor aparece em mais de um escopo, a documentação indica uma ordem de precedência: local primeiro, depois projeto, depois usuário. Na prática, isso permite que uma pessoa sobreponha localmente, por exemplo, o endereço de um servidor de teste sem alterar o que a equipe versionou.

Para escolher o escopo, usa-se a opção de escopo no comando de adição. Um exemplo de forma geral: claude mcp add --transport http nome-do-servidor --scope project https://endereco-do-servidor. As opções vêm antes do nome do servidor, e para servidores locais por stdio o comando do servidor vem depois de um separador. Confira a sintaxe exata na página de MCP da documentação do Claude Code.

Qual escopo escolher? Um guia de decisão

Use estas perguntas, na ordem, para cada servidor que você pretende adicionar:

• O servidor depende de uma credencial pessoal, como um token individual? Use local ou usuário, nunca projeto.
• O servidor é útil só para um repositório específico e toda a equipe precisa dele igual? Use projeto.
• Você quer o servidor em todos os seus repositórios, mas ninguém mais precisa? Use usuário.
• Você ainda está avaliando o servidor e não sabe se confia nele? Use local, até concluir a avaliação.
• O servidor acessa dados pessoais de clientes ou funcionários? Comece em local, com acesso somente leitura, e só promova a projeto depois de revisão de quem responde por LGPD na empresa.

O último item merece atenção. Um servidor compartilhado em projeto vira um padrão da equipe, e padrões se espalham. Se ele toca dados pessoais, a decisão deixa de ser só de desenvolvimento. Para o enquadramento regulatório, veja LGPD e inteligência artificial: o que a empresa deve fazer.

Como versionar a configuração da equipe sem expor credenciais

O ponto central do escopo de projeto é que o .mcp.json vai para o Git. Portanto, tudo o que está nele deve ser seguro para qualquer pessoa com acesso ao repositório, hoje e no histórico futuro. Segredo commitado é segredo vazado, mesmo que você apague depois.

A documentação oficial prevê expansão de variáveis de ambiente no .mcp.json, com a sintaxe de chaves precedidas por cifrão, e também uma forma com valor padrão. Isso funciona em campos como comando, argumentos, variáveis de ambiente do servidor, endereço e cabeçalhos. O resultado é um arquivo que descreve onde ligar e como autenticar, sem conter o valor do segredo.

As práticas que recomendamos, baseadas em implementação e não em documentação oficial:

• Versione o .mcp.json apenas com referências a variáveis, nunca com o valor.
• Documente no README quais variáveis cada pessoa precisa definir e onde obter o valor, sem colocar o valor.
• Use um gerenciador de segredos ou o cofre de senhas da empresa para distribuir tokens, e prefira um token por pessoa, com o menor privilégio possível.
• Adicione ao .gitignore arquivos locais de ambiente, como .env, e confirme que ninguém os commitou antes.
• Rode uma varredura de segredos no CI ou em um hook de pré-commit, para que um deslize seja pego antes do push.
• Para servidores remotos com OAuth, prefira o fluxo de autenticação em que cada pessoa se autentica no próprio cliente (o comando /mcp dentro do Claude Code mostra o estado e permite autenticar), em vez de compartilhar um token da equipe. Para entender o fluxo, a visão geral de OAuth 2.0 do Google é uma boa referência neutra.

Sobre armazenamento e rotação de chaves, veja Chaves de API em agentes de IA: onde guardar e como rotacionar.

Passo a passo para configurar o MCP da equipe

Um roteiro simples, que pode ser feito em uma tarde para um primeiro servidor:

• Passo 1: defina o objetivo. Escreva em uma frase qual tarefa o servidor vai apoiar, por exemplo, consultar o status de um pedido para depurar uma integração.
• Passo 2: audite o servidor antes de instalar. Veja quem mantém, quais ferramentas expõe e quais permissões pede. Há um roteiro em Como auditar um servidor MCP antes de instalar na empresa.
• Passo 3: adicione em escopo local, com credencial de teste e acesso somente leitura. Use o comando claude mcp add e confirme com claude mcp list e claude mcp get.
• Passo 4: teste dentro do Claude Code com o comando /mcp, verificando o status da conexão e quais ferramentas aparecem.
• Passo 5: ajuste as permissões. Defina quais ferramentas do servidor o Claude Code pode usar sem perguntar e quais exigem confirmação. O guia de segurança no Claude Code: permissões, sandbox e segredos detalha esse controle.
• Passo 6: promova a projeto. Adicione o servidor com escopo de projeto, substitua qualquer valor sensível por variável de ambiente e revise o diff do .mcp.json como revisaria código.
• Passo 7: comunique e registre. Avise a equipe, atualize o README com as variáveis necessárias e anote quem aprovou o servidor e quando.
• Passo 8: revise periodicamente. Remova servidores sem uso com claude mcp remove e rotacione tokens em uma cadência definida.

O que acontece quando alguém clona o repositório

Quando uma pessoa abre o projeto e há um .mcp.json, o Claude Code pede aprovação antes de usar os servidores de projeto, segundo a documentação. Isso existe porque um arquivo versionado pode ter sido alterado por qualquer colaborador, e um servidor MCP pode executar comandos na máquina de quem o usa.

Trate esse aviso como parte do processo de revisão. Duas consequências práticas:

• Mudanças no .mcp.json devem passar por pull request com revisão de alguém responsável por segurança ou plataforma, como qualquer mudança que execute código.
• Se alguém aprovou ou recusou um servidor e quer rever a decisão, a documentação descreve o comando claude mcp reset-project-choices para redefinir essas escolhas.

O risco de injeção de instruções por meio de conteúdo retornado por ferramentas também existe. O guia da OWASP sobre prevenção de prompt injection ajuda a pensar nesse vetor, e a folha da OWASP sobre autorização lembra o princípio central: dar a cada identidade só o acesso de que ela precisa.

Cenário ilustrativo: uma equipe de seis pessoas

Cenário ilustrativo: uma empresa de software com seis desenvolvedores quer que o Claude Code consulte a documentação interna de uma API e, separadamente, um desenvolvedor quer testar um servidor de banco de dados com sua base de homologação.

O servidor de documentação não usa dados pessoais e serve a todos. Depois de auditado, entra no escopo de projeto, com o endereço no .mcp.json e o token referenciado por variável de ambiente. Cada pessoa define a variável com um token próprio, emitido com permissão apenas de leitura.

O servidor de banco de dados fica no escopo local do desenvolvedor que o testa, apontando só para homologação e com usuário de banco somente leitura. Se, depois de uma semana, a equipe achar que vale compartilhar, o grupo revisa quais tabelas ele alcança, confirma que não há dados pessoais reais e só então propõe a mudança para projeto, via pull request.

O resultado é uma configuração compartilhada que não carrega segredos e um experimento que não contamina o repositório.

Como aplicamos o método na adoção de MCP

O método que usamos em projetos de IA se encaixa bem aqui. Mapear: listar quais tarefas da equipe dependem de contexto externo e qual é o processo atual. Limitar: escolher o menor conjunto de servidores, com acesso de leitura e escopo estreito. Pilotar: começar com um servidor e um fluxo real, com registro de uso e um critério de sucesso combinado, no estilo de Como medir um piloto de automação com IA. Transferir: entregar a configuração documentada à equipe, com responsáveis por revisão e rotação, e decidir se expande, ajusta ou encerra.

Para o contexto mais amplo de adoção, veja Claude Code para equipes: guia de adoção com controle.

Perguntas frequentes

Qual é o escopo padrão ao adicionar um servidor MCP no Claude Code? O padrão é o escopo local, que deixa o servidor privado para você e restrito ao projeto atual. Para compartilhar com a equipe, é preciso indicar explicitamente o escopo de projeto ao adicionar. Para ter o servidor em todos os seus projetos, indique o escopo de usuário.

Posso colocar o token direto no .mcp.json se o repositório for privado? Não é recomendado. Repositórios privados mudam de acesso, são clonados, copiados para outros ambientes e mantêm o histórico. Use a expansão de variáveis de ambiente prevista na documentação e distribua os valores por um cofre de segredos.

O que acontece se o mesmo servidor existir em mais de um escopo? A documentação indica precedência: o escopo local prevalece sobre o de projeto, que prevalece sobre o de usuário. Isso permite sobrescrever localmente um endereço ou parâmetro sem alterar o arquivo da equipe, mas convém evitar nomes duplicados para não gerar confusão.

Preciso de um servidor MCP para cada sistema da empresa? Não. Comece pelo fluxo que mais depende de contexto externo e avalie se uma API direta, um webhook ou um MCP resolve melhor, como discutimos em Integrar IA ao CRM: API, webhooks ou MCP. Se o sistema for interno, considere criar o servidor começando por leitura, como em Como criar servidor MCP para o sistema interno.

Fontes

• Claude Code: conectar ferramentas via MCP (documentação oficial)
• Model Context Protocol: introdução
• OWASP: guia de autorização
• OWASP: prevenção de prompt injection