Domine o arquivo de configuração que conecta o Claude Desktop aos MCP Servers.
O arquivo claude_desktop_config.json é o ponto de conexão entre o Claude Desktop e o mundo dos MCP Servers. É um arquivo JSON simples que lista todos os servidores MCP que o Claude pode acessar. Sem ele, o Claude Desktop não sabe da existência de nenhuma ferramenta externa — ele funciona apenas como um chat convencional.
O claude_desktop_config.json é um arquivo de configuração em formato JSON que serve como o "catálogo" de MCP Servers disponíveis para o Claude Desktop. Cada entrada neste arquivo descreve um server: seu nome, o comando para iniciá-lo e os argumentos necessários. Quando o Claude Desktop inicia, ele lê este arquivo e tenta conectar-se a cada server listado. Se o arquivo não existir ou estiver vazio, o Claude não terá acesso a nenhuma ferramenta MCP — funcionando apenas como assistente de chat sem ferramentas externas.
Pense no config.json como a "lista de contatos" do Claude Desktop. Assim como seu telefone só pode ligar para números que estão na agenda, o Claude Desktop só pode usar tools de servers que estão no config.json. Adicionar um server ao arquivo é como adicionar um novo contato — a partir daquele momento, o Claude sabe que aquele server existe e pode se conectar a ele.
O arquivo de configuração fica em um diretório específico para cada sistema operacional. É importante saber exatamente onde ele está, pois você editará este arquivo com frequência ao longo do curso. Se o arquivo ou o diretório não existirem ainda, você precisará criá-los manualmente.
O caminho completo do arquivo varia por sistema operacional. O Claude Desktop procura o arquivo sempre no mesmo local, e não há como alterar esse caminho. Você precisa colocar o arquivo exatamente no diretório esperado para que o Claude o encontre.
~/Library/Application Support/Claude/claude_desktop_config.json
Abrir no terminal: open ~/Library/Application\ Support/Claude/
%APPDATA%\Claude\claude_desktop_config.json
Abrir no Explorer: explorer %APPDATA%\Claude
~/.config/Claude/claude_desktop_config.json
Abrir no terminal: xdg-open ~/.config/Claude/
O arquivo pode não existir inicialmente. Se o diretório Claude existir mas o arquivo não, crie-o manualmente com o conteúdo mínimo: {"mcpServers": {}}. Se nem o diretório existir, crie-o também. No macOS, a pasta Library é oculta por padrão — use Cmd+Shift+. no Finder para exibir pastas ocultas, ou navegue via terminal.
Entender a estrutura do arquivo de configuração é fundamental. Ele segue um formato JSON bem definido, com uma hierarquia simples e previsível. Uma vez que você compreenda o padrão, adicionar novos servers se torna uma tarefa mecânica de poucos segundos.
A estrutura do arquivo é um objeto JSON com um campo principal: "mcpServers". Dentro dele, cada server é representado como uma chave (o nome do server) apontando para um objeto com dois campos obrigatórios:
"python", "npx", "node")["-y", "@pacote/server"])Opcionalmente, um server pode ter o campo "env" para variáveis de ambiente (como API keys).
Aqui está um exemplo completo e comentado do formato:
{
"mcpServers": {
"meu-server": {
"command": "npx",
"args": ["-y", "@pacote/mcp-server"]
},
"outro-server": {
"command": "python",
"args": ["-m", "meu_server"],
"env": {
"API_KEY": "sua-chave-aqui"
}
}
}
}
Cada server é independente. Você pode ter quantos quiser, desde que cada nome seja único.
Agora que você entende a estrutura do arquivo, vamos ao processo prático de registrar um novo MCP Server. Cada server precisa de um nome identificador, um comando de execução e os argumentos corretos. Seguir o processo passo a passo garante que tudo funcione na primeira tentativa.
Registrar um MCP Server significa adicionar uma nova entrada no objeto "mcpServers" do config.json. Cada entrada precisa de: um nome (a chave do objeto — deve ser descritivo e único), um command (o executável: python, npx, node, uvx, etc.), e args (um array com o caminho ou pacote do server e seus argumentos). O Claude Desktop usará essas informações para iniciar o server automaticamente quando precisar.
Defina um nome descritivo para o server. Use kebab-case (ex: meu-filesystem, github-tools). O nome deve indicar claramente o que o server faz.
Identifique o executável correto: npx para pacotes npm, python ou uvx para servers Python, node para scripts JS diretos.
Monte o array de argumentos: para npx, inclua "-y" seguido do nome do pacote e quaisquer argumentos do server. Para Python, use "-m" seguido do módulo.
Salve o arquivo config.json, feche o Claude Desktop completamente e reabra-o. O novo server deve aparecer nas tools disponíveis (ícone de martelo).
Configurar o arquivo JSON pela primeira vez é simples, mas alguns erros sutis podem impedir que os MCP Servers sejam carregados. Conhecer os problemas mais comuns e saber diagnosticá-los economiza horas de frustração. A maioria dos problemas se resume a JSON mal formatado ou caminhos incorretos.
Os erros mais frequentes na configuração do config.json são:
\\) ou usar barras normais (/).command especificado não está no PATH do sistema. O npx ou python não são encontrados pelo Claude Desktop.O Claude Desktop não exibe mensagens de erro claras quando o config.json tem problemas. Se os servers não aparecerem após reiniciar, o primeiro passo é sempre validar o JSON. Cole o conteúdo do arquivo em jsonlint.com ou use a validação do VS Code (que sublinha erros de sintaxe automaticamente). Uma única vírgula a mais pode invalidar todo o arquivo.
Depois de criar ou editar o config.json, é essencial validar que tudo está funcionando. A validação envolve reiniciar o Claude Desktop, verificar que os servers aparecem na interface e confirmar que as tools estão disponíveis. Um processo simples, mas que precisa ser feito corretamente.
A validação da configuração segue um fluxo preciso: salvar o arquivo config.json, fechar completamente o Claude Desktop (não apenas minimizar — fechar de verdade, incluindo a bandeja do sistema), reabrir o aplicativo, e verificar o ícone de martelo (🔨) na área de input do chat. Se o ícone aparecer, clique nele para ver a lista de tools disponíveis. Se os servers estiverem conectados, você verá os nomes das tools de cada server. Se o ícone não aparecer, há um problema na configuração que precisa ser investigado.
Salve o config.json e feche completamente o Claude Desktop. No Windows, verifique a bandeja do sistema (system tray). No macOS, use Cmd+Q.
Abra o Claude Desktop novamente. Aguarde alguns segundos para que os servers sejam iniciados. Procure o ícone de martelo (🔨) próximo ao campo de input.
Clique no ícone de martelo para ver a lista de tools. Cada server contribui com suas próprias tools. Verifique que todas as esperadas estão listadas.
Se o ícone não aparecer, verifique os logs do Claude Desktop para mensagens de erro relacionadas à inicialização dos servers MCP.
Se tudo der certo, o ícone de martelo mostrará um número ao lado — indicando quantas tools estão disponíveis. Clicando nele, você verá cada tool com seu nome e descrição. Essa é a confirmação definitiva de que o MCP está funcionando. No próximo módulo, vamos fazer exatamente isso com um server real de exemplo.
Próximo Módulo: 2.6 — Primeiro Teste: MCP Server de Exemplo