Localização do arquivo de configuração MCP do Claude Code e suas opções explicadas

Você executa claude mcp add, o servidor conecta e, uma semana depois, um colega pergunta onde foi parar aquela configuração. O Claude Code não guarda a configuração MCP em um único arquivo organizado. Ele a espalha por ~/.claude.json, um .mcp.json no nível do projeto, vários arquivos settings.json e, em configurações de empresa, um arquivo de política gerenciada. Editar o arquivo errado não muda nada. Editar o certo sem conhecer a ordem de precedência faz com que outra definição vença sem que você perceba.

Este artigo mapeia cada localização no macOS, Windows e Linux, mostra qual definição vence quando dois arquivos citam o mesmo servidor e lista os comandos, variáveis de ambiente e configurações de timeout que importam no dia a dia. Todo caminho e opção abaixo foi conferido com a documentação atual do Claude Code, então você pode copiá-los como estão.

Onde os arquivos realmente ficam

O Claude Code tem três escopos para os servidores que você mesmo adiciona, mais uma camada da organização por cima deles. O escopo define duas coisas: quais projetos carregam o servidor e se a definição acompanha o repositório.

Três escopos, três locais

Escopo local é o padrão. Um servidor adicionado sem --scope carrega apenas no projeto onde você executou o comando e continua privado para você. O Claude Code o grava em ~/.claude.json, no caminho desse projeto:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Copiar prompt

Escopo de projeto grava um arquivo .mcp.json na raiz do repositório. Ele foi feito para ser versionado, para que todos da equipe tenham as mesmas ferramentas. Escopo de usuário guarda a definição no mesmo arquivo ~/.claude.json, fora de qualquer caminho de projeto, para que todos os projetos que você abrir a vejam.

💡 Regra rápida: um servidor privado ou experimental pertence ao escopo local. Uma ferramenta compartilhada da equipe pertence ao escopo de projeto. Uma ferramenta pessoal que você quer em todos os repositórios pertence ao escopo de usuário.

Caminhos no Windows, macOS e Linux

No Windows, ~ significa %USERPROFILE%, então o arquivo em nível de usuário é %USERPROFILE%\.claude.json. O arquivo .mcp.json é relativo à raiz do projeto em todos os sistemas. Só o arquivo gerenciado muda conforme o sistema operacional, porque fica em um diretório do sistema controlado por um administrador.

Se quiser que os arquivos do diretório pessoal fiquem em outro lugar, defina CLAUDE_CONFIG_DIR. O Claude Code passa a guardar ali suas configurações, o histórico de sessões e os plugins, em vez de ~/.claude.

A armadilha do nome "local"

A palavra "local" tem dois significados diferentes no Claude Code. O escopo local do MCP fica em ~/.claude.json, no seu diretório pessoal. As configurações locais gerais ficam em .claude/settings.local.json, dentro do projeto. Pesquisar settings.local.json por um servidor MCP adicionado com o escopo padrão não encontra nada, e essa única confusão responde por grande parte das dúvidas do tipo "onde foi parar meu servidor?".

💡 Definições de servidor vão em .mcp.json ou ~/.claude.json, e os comandos claude mcp as escrevem para você. Os arquivos settings.json guardam aprovações, listas de permissão e listas de bloqueio, que aparecem mais adiante.

Por dentro do arquivo .mcp.json

Ao adicionar um servidor com --scope project, o Claude Code cria ou atualiza este arquivo automaticamente. Você também pode escrevê-lo à mão e fazer commit dele. Ele tem um campo envoltório, mcpServers, e uma entrada por servidor.

Um exemplo funcional

{
  "mcpServers": {
    "docs-search": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SERVICE_TOKEN}"
      }
    },
    "local-files": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/files-server"],
      "env": {
        "ROOT_DIR": "${PROJECT_ROOT:-.}"
      },
      "timeout": 600000
    }
  }
}

Copiar prompt

O campo type aceita http, sse, stdio e ws. O nome streamable-http funciona como alias de http, o que significa que um trecho copiado da própria documentação de um servidor geralmente carrega sem edições. Uma entrada stdio precisa de command e, opcionalmente, de args e env. Uma entrada remota precisa de url e, opcionalmente, de headers.

Um detalhe pega muita gente quando cola config de outro cliente, como o Claude Desktop. O mesmo envoltório mcpServers funciona dentro de .mcp.json, mas claude mcp add-json espera apenas o objeto dentro do envoltório, e não o envoltório em si.

Variáveis de ambiente no lugar de segredos

Como .mcp.json recebe commit, tokens nunca devem ficar nele. O Claude Code expande duas formas de referência a variáveis:

• ${VAR} é expandido para o valor de VAR.
• ${VAR:-default} é expandido para VAR quando estiver definida, e para default caso contrário.

A expansão funciona em valores de command, args, env, url e headers. Se uma variável não estiver definida e não tiver valor padrão, o arquivo ainda assim é carregado. O Claude Code exibe um aviso de variável ausente para esse servidor em claude mcp list e usa o texto bruto ${VAR} como está, por isso um servidor pode falhar com uma string literal desconcertante no cabeçalho.

Há também uma regra de segurança. Nos url e headers de um servidor remoto, variáveis com credenciais, como ANTHROPIC_AUTH_TOKEN e NPM_TOKEN, são lidas como vazias. Isso impede que um repositório clonado envie suas credenciais do Claude Code ou da nuvem para um servidor que ele mencione.

💡 Exporte o token real no perfil do seu shell ou no gerenciador de segredos, e faça commit apenas da referência ${SERVICE_TOKEN}.

Adicionando servidores pelo terminal

Você raramente precisa mexer no JSON manualmente. A família claude mcp add grava no arquivo certo para o escopo escolhido, e é a forma mais segura de evitar um erro de digitação que quebre ~/.claude.json.

Comandos HTTP e stdio

# Remote HTTP server with a bearer token
claude mcp add --transport http docs-search https://example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local stdio server. The -- separates Claude's options from the server command
claude mcp add --transport stdio --env SERVICE_TOKEN=abc123 local-files -- npx -y @example/files-server

# Shared with the team and written to .mcp.json
claude mcp add --scope project --transport http docs-search https://example.com/mcp

Copiar prompt

Em servidores stdio, o traço duplo não é opcional. Tudo antes dele pertence ao Claude Code, e tudo depois é o comando que inicia o servidor.

Servidores remotos usam http ou sse, enquanto um processo local usa stdio. Servidores WebSocket não têm uma opção dedicada, então você os adiciona pelo JSON:

claude mcp add-json events-server '{"type":"ws","url":"wss://example.com/events"}'

Copiar prompt

Servidores que usam OAuth aceitam --client-id, --client-secret e --callback-port, e claude mcp login <name> faz o login pela linha de comando.

Verificando o que conectou

Três comandos respondem à maioria das dúvidas: claude mcp list mostra todos os servidores, claude mcp get <name> mostra um, e claude mcp remove <name> remove um. Dentro de uma sessão, /mcp abre a mesma visão e permite autenticar.

Qual definição vence

Quando o mesmo servidor aparece em mais de um lugar, o Claude Code se conecta a ele uma vez e usa a fonte de maior precedência.

Precedência, da mais alta para a mais baixa

1. Um servidor da configuração gerenciada managedMcpServers (Claude Code v2.1.259 ou posterior)
2. Escopo local
3. Escopo de projeto
4. Escopo de usuário
5. Servidores fornecidos por plugins
6. Conectores do claude.ai

O Claude Code identifica duplicatas entre os três escopos pelo nome. Ele identifica plugins e conectores pelo endpoint, então um que aponte para a mesma URL ou o mesmo comando de um servidor ativo acima dele é considerado uma duplicata.

O detalhe mais importante: a entrada inteira da fonte vencedora é usada, e os campos não são mesclados. Suponha que docs-search exista no escopo de usuário com um cabeçalho Authorization e de novo no escopo de projeto sem ele. A definição do projeto vence por inteiro, e o cabeçalho da entrada do usuário nunca aparece.

Prompts de aprovação para servidores compartilhados

Por motivos de segurança, o Claude Code pede aprovação em sessões interativas antes de usar um servidor de escopo de projeto de .mcp.json. Três configurações controlam o resultado:

{
  "enabledMcpjsonServers": ["docs-search"],
  "disabledMcpjsonServers": ["local-files"]
}

Copiar prompt

Fez uma escolha da qual se arrependeu? claude mcp reset-project-choices limpa as aprovações.

Desde a v2.1.196, um repositório clonado não consegue aprovar os próprios servidores. Aprovações commitadas no .claude/settings.json do projeto são ignoradas em uma pasta que você não confiou, e o servidor permanece em ⏸ Pending approval. Aprovações do seu arquivo de configurações de usuário, ~/.claude/settings.json, das configurações gerenciadas e de --settings continuam valendo. Um .claude/settings.local.json não versionado também funciona, assim que a pasta for confiada.

Execuções não interativas, como claude -p, carregam servidores do projeto sem pedir confirmação, a menos que você as inicie com --strict-mcp-config. Essa opção diz ao Claude Code para usar apenas os servidores passados com --mcp-config.

💡 Revise .mcp.json em um pull request do mesmo jeito que revisaria um script. Uma entrada stdio executa um comando na máquina de cada membro da equipe.

Arquivos de configurações e controles de política

Arquivos de configurações, da maior prioridade para a menor

Uma configuração em um nível mais alto substitui a mesma configuração em um nível mais baixo. ~/.claude.json é um arquivo separado que o Claude Code grava para si mesmo. Ele guarda sua sessão de login, suas configurações de servidores MCP, o estado por projeto, como decisões de confiança, e as opções globais que /config altera. Você não precisa editá-lo à mão.

Listas de permissão e servidores gerenciados

Equipes que precisam de controle têm quatro ferramentas, listadas aqui da mais leve para a mais rigorosa:

• disabledMcpServers permite que um usuário desative servidores específicos de usuário, de plugins, gerenciados ou do claude.ai.
• allowedMcpServers e deniedMcpServers filtram pelo nome do servidor ou por um padrão de serverUrl.
• managedMcpServers é uma configuração gerenciada que fornece servidores a todos, junto com os que os usuários adicionam.
• managed-mcp.json implanta um conjunto fixo de servidores a partir dos caminhos do sistema mostrados antes.

Implantar managed-mcp.json tem um efeito colateral que vale conhecer. Por padrão, ele suprime os conectores do claude.ai que o Claude Code busca por conta própria. Para carregá-los junto dos seus servidores gerenciados, defina "allowAllClaudeAiMcps": true em uma fonte de configurações gerenciadas. Definir a variável de ambiente ENABLE_CLAUDEAI_MCP_SERVERS=false desliga os conectores em uma única máquina.

Timeouts e limites de saída

Timeouts de inicialização e de ferramentas

Dois cronômetros importam, e é fácil confundi-los.

O timeout por servidor substitui a variável de ambiente MCP_TOOL_TIMEOUT apenas para esse servidor. Valores abaixo de 1000 são ignorados e passam para MCP_TOOL_TIMEOUT. Quando essa variável não está definida, o padrão é de cerca de 28 horas. Notificações de progresso do servidor não estendem o limite.

Saídas grandes de ferramentas

O Claude Code avisa quando qualquer ferramenta MCP retorna mais de 10.000 tokens e limita a saída a 25.000 tokens por padrão. Aumente o limite com MAX_MCP_OUTPUT_TOKENS=50000 claude, ou torne-o permanente pelo campo env de um arquivo de configurações:

{
  "env": {
    "MCP_TIMEOUT": "10000",
    "MAX_MCP_OUTPUT_TOKENS": "50000"
  }
}

Copiar prompt

Como corrigir uma config quebrada rapidamente

Sintomas e correções

Se ~/.claude.json falhar na leitura, o Claude Code copia o arquivo quebrado para ~/.claude/backups/.claude.json.corrupted.<timestamp> e pergunta se você quer sair e corrigi-lo à mão ou restaurar a configuração padrão. Para recuperar seu estado anterior, copie um dos cinco arquivos .claude.json.backup.<timestamp> mais recentes de ~/.claude/backups/ de volta para o lugar.

💡 Edições manuais em ~/.claude.json raramente valem o risco. Prefira claude mcp add, add-json e remove, e guarde uma cópia do arquivo antes de qualquer alteração manual.

Crie seus próprios visuais com o PicassoIA

O trabalho com config termina no momento em que um servidor mostra ✔ Connected, mas documentá-lo leva mais tempo do que fazê-lo. Capturas de tela do README, diagramas de integração e pequenos vídeos de uma sessão de terminal atrasam uma equipe. É aí que o PicassoIA ajuda, com modelos de texto, imagem e vídeo em um só lugar.

Use o Claude Sonnet 5 no PicassoIA

O Claude Sonnet 5 é um modelo de linguagem criado para tarefas de programação e uso de ferramentas, o que o torna útil para rascunhar uma entrada de config ou revisar uma antes de fazer o commit. A página do modelo expõe estas entradas:

1. Abra a página do modelo e cole seu pedido em Prompt. Por exemplo: "Converta este comando claude mcp add em uma entrada .mcp.json cujo cabeçalho Authorization leia de uma variável de ambiente."
2. Defina Effort. O padrão é low, que desliga o pensamento para a resposta mais rápida e barata. Escolha high ou max quando um bug se espalhar por vários arquivos.
3. Adicione um System Prompt, como "Responda apenas com JSON válido, sem comentários", e reutilize-o ao longo da sessão.
4. Deixe Max Tokens como está, a menos que a saída seja longa. O padrão é 8.192.
5. Anexe uma imagem se tiver uma captura de tela de um erro. O modelo a lê como contexto.
6. Execute e depois verifique. Cole o resultado em .mcp.json e rode claude mcp get <name> para confirmar que o servidor conectou.

💡 Trate a config gerada como um rascunho. Caminhos, opções e configurações mudam entre versões, então confira cada um na documentação oficial.

Para o lado visual, modelos de texto para imagem, como PicassoIA Image e Seedream 5 Pro, podem criar a arte de cabeçalho para uma página de documentação ou um post de changelog. Para ajustar uma imagem que você já tem, abra o PicassoIA Image Editor Pro. Para movimento, o PicassoIA Video e o Seedance 2.5 Lite transformam um prompt ou uma imagem parada em um clipe curto.

O PicassoIA também oferece conexões MCP para seus modelos de imagem e vídeo, gerenciadas na sua conta em picassoia.com/en/mcp/accounts. Quando tiver os dados de conexão, um servidor HTTP é adicionado com o mesmo padrão claude mcp add --transport http mostrado acima.

Escolha um modelo, escreva um prompt e gere sua primeira imagem de cabeçalho ou clipe para o próximo README. Teste algumas variações, compare-as lado a lado e fique com a que combinar. Tudo está disponível em picassoia.com/en/all-models.