Você cola um comando de um README, pressiona Enter, e o Claude Code diz "Added". Depois você abre uma nova sessão e as ferramentas não aparecem em lugar nenhum. Quando isso acontece, a configuração de MCP do Claude Code geralmente se resume a duas perguntas: em qual escopo o servidor foi registrado e se ele realmente se conectou. Este guia responde às duas com saída real de terminal do Claude Code 2.1.300, usando o servidor MCP da Atlas Cloud como exemplo.
Principais pontos
- Execute claude mcp add com um nome de servidor, dois traços e o comando que inicia o servidor.
- O escopo local é o padrão; adicione --scope user para todos os projetos, ou --scope project para compartilhar .mcp.json.
- O comando claude mcp list mostra o status ao vivo de cada servidor, incluindo conectores da sua conta claude.ai.
- O Claude Desktop lê seu próprio claude_desktop_config.json, então servidores adicionados no Claude Code ficam separados.
- _O servidor MCP da Atlas Cloud adiciona geração de vídeo do Seedance 2.5 ao Claude Code com um comando.
Onde o Claude Code armazena a configuração de MCP
Cada servidor que você adiciona fica em um de três escopos, e o escopo decide duas coisas: quais projetos podem vê-lo e qual arquivo o contém. A documentação de MCP do Claude Code os define assim.
| Escopo | Flag | Carregado em | Salvo em | Compartilhado com sua equipe |
|---|---|---|---|---|
| Local (padrão) | --scope local, ou nenhuma flag | Apenas o projeto atual | ~/.claude.json, sob o caminho desse projeto | Não |
| Projeto | --scope project | Apenas o projeto atual | .mcp.json na raiz do projeto | Sim, por controle de versão |
| Usuário | --scope user | Todos os seus projetos | ~/.claude.json | Não |
No Windows, ~/.claude.json é o arquivo na sua pasta de usuário, por exemplo C:\Users\you\.claude.json. As entradas local e de usuário vão para esse mesmo arquivo, e é por isso que "eu adicionei, mas sumiu" normalmente significa que você o adicionou localmente em outra pasta.
Quando o mesmo nome existe em mais de um escopo, o Claude Code usa uma única definição e não mescla campos. O local tem precedência sobre o projeto, e o projeto sobre o usuário.
O comando Claude MCP Add, com a Atlas Cloud como exemplo
A Atlas Cloud publica o atlascloud-mcp, um servidor MCP (código-fonte no GitHub) que permite ao Claude enviar tarefas de imagem e vídeo para os modelos da Atlas e trazer os arquivos finalizados de volta para a sessão. Este clipe foi o que nossa configuração final produziu a partir de uma única solicitação no Claude Code:
Ele roda localmente via npx, então a única configuração necessária é Node.js 18 ou mais recente e uma chave de API. Veja o ciclo completo de adicionar e verificar em dois comandos.
Sua chave vem do painel API Keys nas configurações do console da Atlas Cloud. A lista completa de clientes está na página de configuração do servidor MCP.
Método 1: Adicionar um servidor local com claude mcp add
- Exporte sua chave e depois deixe o Claude Code adicionar servidores MCP com uma linha. Os dois traços importam: tudo antes deles é para o Claude Code (nome, escopo, env), e tudo depois é o comando que inicia o servidor.
plaintext1export ATLASCLOUD_API_KEY="your-api-key" 2claude mcp add atlascloud --scope user -e ATLASCLOUD_API_KEY=$ATLASCLOUD_API_KEY -- npx -y atlascloud-mcp
2. Verifique o resultado. Na captura de tela, a linha Scope mostra "User config (available in all your projects)" e Status mostra Connected.
plaintext1claude mcp get atlascloud
Se omitir --scope user, o servidor existirá apenas na pasta em que você executou o comando. A flag -e armazena a chave na entrada do servidor, então ele continua funcionando em um terminal onde você não a exportou.
Uma observação para usuários do Windows: alguns guias mandam envolver o npx em cmd /c. No Windows 11 com Claude Code 2.1.300, o comando simples acima se conectou de primeira, sem precisar de wrapper.
Método 2: Colar um bloco JSON com claude mcp add-json
Muitos READMEs e páginas de configuração de MCP, incluindo os da Atlas, fornecem um bloco JSON em vez de um comando. Passe-o diretamente para add-json:
plaintext1claude mcp add-json atlascloud '{"command":"npx","args":["-y","atlascloud-mcp"],"env":{"ATLASCLOUD_API_KEY":"your-api-key"}}'
Nossa entrada de teste se chama atlascloud-json para que ambas possam coexistir. Coloque o JSON entre aspas simples no bash ou zsh. O Windows PowerShell 5.1 pode remover as aspas duplas internas, então execute este comando no Git Bash, WSL ou PowerShell 7.
Configuração do servidor MCP do Claude Code em .mcp.json
Use o escopo de projeto quando a equipe inteira deve receber o mesmo servidor. Ele grava .mcp.json na raiz do projeto, que você versiona como qualquer arquivo de configuração.
O problema é a chave de API. Não a versione. O Claude Code expande VARe{VAR} e VARe{VAR:-default} dentro de .mcp.json, então a variável de ambiente de cada membro da equipe preenche o valor na inicialização. Use aspas simples no valor de -e para que seu shell repasse o nome da variável em vez da sua chave:
plaintext1claude mcp add atlascloud --scope project -e 'ATLASCLOUD_API_KEY=${ATLASCLOUD_API_KEY}' -- npx -y atlascloud-mcp
Um servidor novo em .mcp.json mostra "Pending approval" e não se conecta até alguém executar claude nessa pasta e aprová-lo. É uma verificação de segurança: um repositório clonado não pode iniciar programas na sua máquina sozinho.
| Você tem | Use | Fica em |
|---|---|---|
| Um comando de instalação de uma linha | claude mcp add | Local, ou o escopo que você passar |
| Um bloco JSON de um README | claude mcp add-json | Local, ou o escopo que você passar |
| Um servidor de que o repositório inteiro precisa | --scope project, depois faça commit do .mcp.json | .mcp.json |
Verifique seus servidores com o comando claude mcp list
O comando claude mcp list faz verificação de integridade dos servidores configurados e imprime uma linha para cada um. O status no fim da linha é a parte que importa.
| Status | O que significa | O que fazer |
|---|---|---|
| ✔ Connected | O servidor iniciou e respondeu | Nada; abra uma nova sessão e as ferramentas estarão lá |
| ! Needs authentication | Um servidor remoto quer um login OAuth | Execute /mcp dentro do Claude Code e escolha Authenticate |
| ✘ Failed to connect | O comando falhou ou expirou | Execute o comando do servidor manualmente para ver o erro |
| ⏸ Pending approval | Uma entrada .mcp.json não aprovada | Execute claude nessa pasta e aprove-a |
Se você estiver conectado com uma conta claude.ai, a lista também inclui os conectores dessa conta, cada um prefixado com "claude.ai". A nossa mostrou mais de 20. Para ver apenas o que você configurou, defina ENABLE_CLAUDEAI_MCP_SERVERS=false para essa sessão do shell.
Claude Remove MCP: exclua um servidor do escopo certo
Adicione -s com o escopo quando souber qual é, e sempre que o mesmo nome existir em mais de um escopo.
plaintext1claude mcp remove atlascloud -s user
A última linha de claude mcp get imprime o comando exato de remoção, incluindo o escopo. Para servidores remotos, a remoção também exclui os tokens OAuth que o Claude Code armazenou.
Configuração de MCP do Claude Desktop em claude_desktop_config.json
O Claude Desktop não lê ~/.claude.json. Ele tem seu próprio arquivo, e você o edita manualmente: abra Settings, escolha Developer, clique em Edit Config, cole o bloco e feche e reabra o aplicativo.
| Sistema | Local de claude_desktop_config.json |
|---|---|
| macOS | ~/Library/Application Support/Claude/ |
| Windows | %APPDATA%\Claude\ |
plaintext1{ 2 "mcpServers": { 3 "atlascloud": { 4 "command": "npx", 5 "args": ["-y", "atlascloud-mcp"], 6 "env": { 7 "ATLASCLOUD_API_KEY": "your-api-key" 8 } 9 } 10 } 11}
Já tem servidores no Desktop? O Claude Code pode copiá-los com claude mcp add-from-claude-desktop, que abre um seletor. O comando funciona apenas no macOS e no WSL, então usuários do Windows nativo devem colar o mesmo JSON em add-json. Nosso passo a passo em vídeo do Claude mostra as telas de configurações do Desktop passo a passo.
Teste a configuração com um vídeo do Seedance 2.5 a partir do Claude Code
Um status Connected só prova que o servidor iniciou. Para ver um trabalho real passar, enviamos o clipe do grou do início deste guia. Com o atlascloud registrado, o Claude Code chamou o Seedance 2.5, o modelo de vídeo principal da ByteDance, com esta solicitação:
plaintext1Use the atlascloud MCP server to make an 8-second 16:9 video at 720p with bytedance/seedance-2.5/text-to-video, audio on. Prompt: Close-up on a walnut desk at blue hour. A white origami crane folded from graph paper slowly lifts its wings, hops once, then glides off the desk edge past a steaming ceramic mug while rain streaks the window behind. Warm desk-lamp key light, cool window fill, shallow depth of field, 50mm lens, slow push-in, subtle film grain. Sound: soft rain, a paper rustle, a faint lamp hum.
| Etapa | Ferramenta que o Claude chamou | O que retornou |
|---|---|---|
| Ler os parâmetros do modelo | atlas_get_model_info | Duração de 4 a 30 segundos, resoluções a partir de 480p, áudio ativado por padrão |
| Enviar o trabalho | atlas_generate_video | Um ID de previsão |
| Verificar o trabalho | atlas_get_prediction | Um MP4 de 8 segundos em 1280x720 com sua própria faixa de áudio |
O GIF no início deste guia é um corte silencioso desse MP4. Você pode executar o mesmo prompt manualmente no playground do Seedance 2.5 para comparar.
Como adicionar skills ao Claude Code junto com o MCP
Um servidor MCP dá ao Claude ferramentas para chamar. Uma skill dá ao Claude conhecimento escrito que ele carrega quando uma tarefa corresponde, como quais parâmetros um modelo aceita ou como planejar um vídeo com vários planos. A Atlas oferece os dois.
plaintext1npx skills add AtlasCloudAI/atlas-cloud-skills
Isso instala três skills do repositório atlas-cloud-skills. Você também pode copiar uma pasta de skill para ~/.claude/skills/ manualmente. As skills leem a mesma variável ATLASCLOUD_API_KEY.
| Skill | O que o Claude obtém disso |
|---|---|
atlas-cloud
plaintext1 | API reference for image, video and chat models, plus code templates in Python, Node.js and cURL |
| seedance-2-5-skill | Planejamento de planos para Seedance: escolher a rota, atribuir referências, vocabulário de câmera e iluminação | | universal-video-prompt-skill | Estruturas de prompt que funcionam em vários modelos de vídeo |
A seedance-2-5-skill faz referência à universal-video-prompt-skill, então instale ambas se quiser suas especificações de prompt entre modelos. Para uma versão de imagem estática da mesma configuração, veja nossos testes de geração de imagens do Claude.
FAQ
O Claude Code pode ser usado como servidor MCP?
Sim. Execute claude mcp serve e o Claude Code inicia como um servidor MCP stdio que não imprime nada e aguarda um cliente. Para usá-lo a partir do Claude Desktop, adicione uma entrada cujo command seja claude e cujos args sejam mcp e serve. Se claude não estiver no seu PATH, coloque o caminho completo do executável no campo command.
Quais servidores MCP devo adicionar ao Claude Code?
Adicione servidores para trabalhos que você repete toda semana. Um servidor de banco de dados compensa se você escreve consultas diariamente; um servidor de mídia como o atlascloud compensa se você produz imagens ou vídeo, já que o Claude escreve o prompt e busca o arquivo em uma única sessão.
Por que meu servidor MCP mostra "Failed to connect"?
Execute o comando do servidor sozinho primeiro. Para o atlascloud, é npx -y atlascloud-mcp, que falha rapidamente se o Node.js for anterior ao 18 ou se o npx não estiver no seu PATH. Se o comando funcionar manualmente, o servidor pode apenas estar iniciando devagar: inicie o Claude Code com MCP_TIMEOUT=10000 para dar 10 segundos a ele.
O Claude Code e o Claude Desktop compartilham servidores MCP?
Não. O Claude Code lê ~/.claude.json e .mcp.json, e o Claude Desktop lê claude_desktop_config.json, então um servidor adicionado em um não aparece no outro. Conectores que você adiciona à sua conta claude.ai são a exceção: eles aparecem no Claude Code automaticamente quando você entra com essa conta.
Conclusão
Uma configuração típica precisa de cinco comandos: add ou add-json para registrar um servidor, list e get para confirmar que ele se conectou, e remove para limpar. Escolha o escopo antes de pressionar Enter e o resto vem em seguida.
Acerte a configuração de MCP do Claude Code uma vez, verifique-a com claude mcp list, e novas sessões nesse escopo abrem com as ferramentas prontas. Se você quiser que o Claude produza imagens e vídeo além de código, o servidor atlascloud com o qual você acabou de praticar é uma boa opção para manter.
