MCP no Claude Code: como adicionar servidores e onde fica a configuração

Como adicionar um servidor MCP ao Claude Code

1. Escolha o transporte

   Use HTTP para servidores remotos hospedados na nuvem; é o transporte recomendado, e o Claude Code recorre ao transporte SSE, já obsoleto, quando um servidor só oferece esse. Use stdio para servidores que rodam como um processo local. No stdio, tudo o que vem depois de -- é repassado ao servidor sem alteração.

   # Servidor HTTP remoto (recomendado para serviços na nuvem)
   claude mcp add --transport http notion https://mcp.notion.com/mcp
   
   # Com um bearer token
   claude mcp add --transport http secure-api https://api.example.com/mcp \
     --header "Authorization: Bearer your-token"
   
   # Servidor stdio local: tudo depois de -- é o comando do próprio servidor
   claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
     -- npx -y airtable-mcp-server

2. Escolha um escopo

   Sem --scope, um servidor é local: só para você, só neste projeto. Adicione --scope project para gravá-lo no .mcp.json e compartilhar com o time, ou --scope user para todos os seus projetos. Veja a tabela abaixo.

3. Faça login se o servidor pedir

   Muitos servidores remotos usam OAuth. Rode /mcp dentro do Claude Code e escolha o servidor para se autenticar, ou claude mcp login <name> no terminal. Execuções headless com -p não conseguem abrir o fluxo de login, então faça login de forma interativa antes.

4. Confira se conectou

   Rode /mcp para ver o status e as ferramentas de cada servidor, e claude mcp list no terminal. Depois peça ao Claude para usar a ferramenta pelo nome.

5. Gerencie seus servidores

   Liste, inspecione, remova ou importe servidores pela linha de comando. Se você quase não usa um servidor, desative-o no /mcp em vez de removê-lo.

   claude mcp list            # todos os servidores configurados
   claude mcp get notion      # os detalhes de um servidor
   claude mcp remove notion   # remove o servidor (rode claude mcp logout notion antes para revogar os tokens)
   claude mcp add-from-claude-desktop   # importa do Claude Desktop (macOS, WSL)

Fonte: documentação do Claude Code, Connect Claude Code to tools via MCP

Escopos do MCP e onde ficam os arquivos de configuração

É aqui que o Claude Code guarda a configuração do MCP. Repare que o escopo "local" do MCP fica em ~/.claude.json, e não em .claude/settings.local.json.

Compartilhe servidores com o .mcp.json

O .mcp.json permite que o time inteiro use os mesmos servidores. Deixe os segredos de fora com variáveis de ambiente: ${VAR} é substituído pelo valor da variável, e ${VAR:-default} usa um valor padrão quando ela não está definida. A expansão funciona em command, args, env, url e headers.

1. Use variáveis em vez de segredos

   O Claude Code pede que cada pessoa aprove os servidores de projeto do .mcp.json na primeira vez; claude mcp reset-project-choices zera essas respostas. Uma entrada JSON com url também precisa de um type, como http.

   {
     "mcpServers": {
       "api-server": {
         "type": "http",
         "url": "${API_BASE_URL:-https://api.example.com}/mcp",
         "headers": {
           "Authorization": "Bearer ${API_KEY}"
         }
       }
     }
   }

Precedência, conectores e outros detalhes

• Quando o mesmo servidor está definido duas vezes, o Claude Code conecta uma vez só, usando o primeiro de: local, project, user, plugin, conector do claude.ai. As entradas não são mescladas; os servidores gerenciados de uma organização têm prioridade sobre todos eles.
• Se você faz login no Claude Code com uma conta do claude.ai, os conectores que você adicionou no claude.ai aparecem automaticamente.
• O Claude Code também pode ser um servidor MCP: claude mcp serve expõe as ferramentas dele para outro cliente, como o Claude Desktop.
• Os servidores também podem oferecer prompts que aparecem como comandos de barra; veja os comandos de barra do Claude Code.
• Remover um servidor remoto apaga os tokens que o Claude Code guardou, mas não os revoga; para isso, rode claude mcp logout <name> antes.

MCP e uso de tokens

As definições de ferramentas são carregadas sob demanda por padrão: só os nomes das ferramentas e as instruções do servidor ficam no contexto até o Claude usar uma ferramenta, então uma lista longa de servidores custa menos do que antes. Mesmo assim, cada servidor acrescenta alguma coisa, então desative no /mcp os que você não usa e prefira uma CLI como gh, aws ou gcloud quando ela existir, já que ela não acrescenta nenhuma lista de ferramentas. Mais em como reduzir o uso de tokens do Claude Code.

Solução de problemas: quando um servidor não conecta

• Aparece pedindo autenticação: abra o /mcp e escolha Re-authenticate, ou rode claude mcp login <name>.
• "has a url but no type": adicione "type": "http" (ou sse ou ws) à entrada JSON; sem um tipo, o Claude Code trata a entrada como stdio.
• As flags de um servidor stdio sumiram: coloque -- antes do comando do servidor para que o Claude Code não as interprete como dele.
• Aviso de variável ausente no claude mcp list: defina a variável ou dê a ela um :-default.
• Um servidor de projeto nunca carrega no claude -p: no modo headless não há pedido de aprovação, então confira as suas configurações ou passe os servidores explicitamente com --mcp-config e --strict-mcp-config.
• Nomes de servidores adicionados com claude mcp só podem ter letras, números, hífens e underscores.

Dê aos seus funcionários de IA as mesmas ferramentas que você usa

O MCP é como o Claude Code chega ao seu gerenciador de issues, ao seu banco de dados ou às suas métricas. O Crewmark transforma uma sessão do Claude Code, Codex, DeepSeek Harness ou OpenCode em um funcionário de IA com um papel, uma meta e um horário de trabalho, e a acorda com um heartbeat para pegar a próxima issue de um quadro, com os servidores MCP do seu projeto disponíveis.

1. Faça commit do .mcp.json

   Servidores com escopo de projeto carregam na sessão do funcionário como na sua; para os servidores que precisam de OAuth, faça login uma vez de forma interativa.

2. Deixe o heartbeat iniciar o trabalho

   Durante o horário de trabalho, o funcionário acorda a cada 15, 30 ou 60 minutos na mesma conversa; veja como deixar o Claude Code proativo.

3. Dê a cada papel só o que ele precisa

   Um funcionário de SEO recebe o Search Console; um programador, o GitHub e o Sentry. Leia o que é um funcionário de IA.

Perguntas frequentes sobre MCP no Claude Code