Como adicionar um servidor MCP ao Claude Code

Adicionando um servidor remoto por HTTP

Um servidor remoto é uma URL. O Claude Code fala HTTP em streaming com ele, então o registro inteiro cabe em uma linha:

claude mcp add --transport http hosttracker https://mcp.host-tracker.com/mcp

O primeiro argumento depois do transporte é o nome que você verá em /mcp e nos nomes das ferramentas; o segundo é o endpoint. Servidores que autenticam com OAuth não precisam de mais nada na linha de comando: na primeira vez que você abrir /mcp, selecione o servidor e o Claude Code abre o navegador para o login e o consentimento, depois guarda o token resultante e o renova sozinho. A partir do Claude Code 2.1.186 também é possível rodar o login sem a sessão interativa, com claude mcp login hosttracker, e adicionar --no-browser em uma máquina sem navegador para obter uma URL que pode ser colada em outro lugar.

Servidores que esperam um token estático em vez disso o recebem como cabeçalho:

claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

Alguns servidores mais antigos ainda falam o transporte SSE. Ele está obsoleto em favor do HTTP, e desde o Claude Code 2.1.265 o --transport http tenta HTTP primeiro e recorre ao SSE se o servidor recusar, então raramente é preciso usar --transport sse.

Adicionando um servidor local

Um servidor local é um programa que o Claude Code inicia para você e com o qual conversa pela entrada e saída padrão. Coloque o comando e os argumentos dele depois de um traço duplo, para que as próprias flags do Claude Code não sejam confundidas com as do servidor:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

As variáveis de ambiente que o servidor precisa passam por --env (forma curta -e), repetida uma vez por variável. Uma armadilha documentada: o analisador de opções lê o que vier depois de --env KEY=value como outro par, então não coloque o nome do servidor logo em seguida; ponha outra opção no meio ou coloque --env antes de --transport:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

Se você já tem a configuração do servidor em JSON, por exemplo a partir do README dele, claude mcp add-json <nome> '<json>' a recebe do jeito que está, incluindo type, command, args e env.

Escolhendo um escopo: este projeto, a equipe ou tudo

Por padrão um servidor é adicionado no escopo local, o que significa apenas este projeto, guardado no seu próprio ~/.claude.json. Existem outros dois escopos:

• --scope project grava a entrada em um arquivo .mcp.json na raiz do repositório. Faça o commit e cada colaborador recebe o mesmo servidor; o Claude Code pede a aprovação de cada pessoa na primeira vez.
• --scope user deixa o servidor disponível em todos os projetos da sua máquina, ainda privado para você.

Quando o mesmo nome existe em mais de um escopo, local prevalece sobre project, e project prevalece sobre user. A entrada inteira vem do escopo vencedor; os campos nunca são combinados entre escopos. Uma divisão sensata é --scope user para serviços ligados à sua própria conta, como um servidor de monitoramento ou de chamados, e --scope project para ferramentas que toda a equipe deve compartilhar.

Conferindo se funciona

Rode claude mcp list fora de uma sessão. Cada servidor mostra um entre alguns status: conectado, precisa de autenticação, falhou ao conectar (com o status HTTP ou o erro anexado desde a 2.1.219), aguardando aprovação para um servidor de projeto ainda não aprovado, ou desativado para este projeto. Dentro de uma sessão, /mcp mostra os mesmos servidores com a contagem de ferramentas deles, deixa você iniciar o login de um que precisa disso, limpar a autenticação dele ou desativá-lo para o projeto atual sem removê-lo.

Um teste funcional rápido é um pedido que só o servidor consegue responder. Com o servidor da HostTracker conectado, pergunte "quais dos meus monitores estão fora do ar agora?" ou "faça uma verificação HTTP em example.com a partir de três localidades"; o assistente deve chamar uma ferramenta com o nome do servidor e citar um resultado que não poderia saber de outra forma. Se nada acontecer, a lista de ferramentas costuma ser o motivo: /mcp mostra zero ferramentas para um servidor que conectou mas falhou na autorização.

Removendo, inspecionando e importando

claude mcp get <nome> mostra a configuração completa e o escopo de um servidor. claude mcp remove <nome> o apaga junto com qualquer token OAuth guardado. Se você configurou servidores primeiro no Claude Desktop, claude mcp add-from-claude-desktop os importa de forma interativa; funciona no macOS e no Windows Subsystem for Linux, não no Windows nativo nem no Linux nativo, e pula um servidor do Desktop cujo nome contenha caracteres que o Claude Code não permite (apenas letras, dígitos, hífens e sublinhados).

Um servidor de monitoramento como primeiro teste

Um serviço de monitoramento é um bom primeiro servidor para conectar porque o resultado de uma chamada de ferramenta é verificável na hora: o assistente diz que um site está no ar, e você pode abri-lo. O servidor da HostTracker não precisa de instalação local, autentica com OAuth no navegador e expõe verificações instantâneas a partir de mais de 300 localidades, além dos monitores, incidentes, janelas de manutenção e páginas de status da sua conta, então "a produção está no ar?" é respondido a partir de pontos de verificação reais, não de dados de treinamento. O guia relacionado sobre configuração e solução de problemas do .mcp.json cobre o formato do arquivo, as variáveis de ambiente e as falhas que aparecem na prática.