Claude Code MCP add: como adicionar um servidor MCP pelo terminal

Fala aí, beleza? MCP virou assunto obrigatório na timeline: todo mundo comentando, todo mundo mostrando print de servidor conectado, e aí tu abre o terminal e não faz ideia de qual linha digitar

O comando que resolve isso é o claude mcp add

Ele pega o transporte, o nome e o endereço (ou o comando) do servidor e grava esses dados num arquivo de configuração do Claude Code (qual arquivo recebe a entrada depende do escopo que tu escolher, e isso a gente destrincha lá embaixo)

Neste post tu vai ver a forma exata do comando, o que precisa ter em mãos ANTES de rodar, os errinhos de ordem que derrubam a linha e como confirmar que o servidor ficou mesmo disponível na sessão 🙂

Se a tua dúvida ainda está um passo atrás, tipo quando um servidor MCP vale a pena, tem post separado só sobre isso

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O que você precisa ter em mãos antes de rodar o comando

Antes de sair digitando, junta essas quatro coisas numa nota:

• O transporte: stdio, http ou sse. Grosso modo, stdio é servidor que roda como processo na tua máquina e http é servidor remoto que já está de pé em algum lugar
• O destino: a URL do servidor remoto, no caso de http, OU o comando que sobe o servidor local com todos os argumentos dele, no caso de stdio
• O nome: um apelido curto pro servidor, que é como tu vai chamar ele depois no claude mcp get e no claude mcp remove
• As credenciais: variável de ambiente via –env quando é stdio, header de autorização via –header quando é http

E se liga nesse detalhe, porque ele economiza uns bons minutos de cabeça quente: o Claude Code salva a configuração SEM checar o token

Ou seja, tu digita a chave errada, o comando termina numa boa, e o problema só aparece bem depois como falha de conexão com 401

Tome cuidado! Copia e cola a credencial, não digita na mão

Como adicionar um servidor MCP no Claude Code passo a passo

Bora ver na prática?

1. Monte a linha base com o transporte

A forma do comando é sempre essa:

claude mcp add --transport <stdio|http|sse> <nome> <url-ou-comando>

A regra de ouro aqui: todas as opções (–transport, –env, –scope, –header) precisam vir ANTES do nome do servidor

Pensa na linha como três blocos em ordem fixa: opções, nome, destino

O erro comum deste passo: escrever o nome primeiro e jogar a opção lá pro fim, do jeito que a gente escreveria numa frase normal

2. Adicione um servidor remoto por http

Esse é o registro mais tranquilo que existe, porque o servidor já está no ar e tu só aponta pra ele

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Lê da esquerda pra direita: opção de transporte, nome (claude-code-docs), URL

O erro comum deste passo: inverter e colocar o nome antes do –transport, o que quebra a ordem que a CLI espera

3. Adicione um servidor stdio usando o separador —

Aqui entra a parte que mais confunde quem nunca rodou o comando

O separador — (dois hífens sozinhos) separa as opções do próprio Claude Code do comando e dos argumentos que sobem o servidor

Tudo que vem depois dele é passado ao servidor sem alteração nenhuma

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

E quando o teu servidor tem flags próprias, fica assim:

claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080

Esse segundo exemplo roda python server.py –port 8080 com KEY=value no ambiente

"E se eu esquecer o separador?" Boa pergunta

Sem ele, o Claude Code tentaria interpretar as flags do servidor (o –port, por exemplo) como opções DELE mesmo

O erro comum deste passo: exatamente esse, esquecer o — e ver o Claude Code comendo as flags que eram do servidor

4. Passe as credenciais do jeito certo

Em stdio, a credencial vai por variável de ambiente com –env, que aceita vários pares KEY=value

Em http, a credencial de token estático vai por header, e o header é opção, então entra antes do nome, igual todo o resto:

claude mcp add --transport http --header "Authorization: Bearer SEU_TOKEN" <nome> <url>

A flag –header tem forma curta -H e é repetível, então dá pra mandar vários headers na mesma linha

E tem um truque MUITO útil: os headers aceitam expansão de variável de ambiente com a sintaxe ${VAR} ou ${VAR:-default}

Assim tu versiona a configuração sem versionar o segredo:

claude mcp add --transport http --header "Authorization: Bearer ${MCP_TOKEN}" meuserver https://exemplo.com/mcp

O erro comum deste passo: colocar o nome do servidor logo depois do –env

Como o –env aceita vários pares, a CLI lê o nome como se fosse mais um KEY=value e rejeita

A saída é simples: coloca pelo menos outra opção entre o –env e o nome, igual nos exemplos oficiais, onde o –transport fica no meio 😀

5. Rode a linha e confira que salvou

Comando digitado, enter dado, sem erro na tela? Beleza

Agora não confia só no silêncio do terminal, vai conferir:

claude mcp list

O erro comum deste passo: achar que "não deu erro" é o mesmo que "está conectado"

Lembra que a config é salva sem validação, então a checagem de verdade é a próxima seção

Como confirmar que o servidor ficou disponível na sessão

1. Leia o status no claude mcp list

O claude mcp list mostra o status de saúde do lado de cada servidor:

Quando o status é Failed to connect, o próprio claude mcp list acrescenta o detalhe da falha na mesma linha, com o status HTTP ou código de erro e o texto de erro devolvido pelo servidor

Esse detalhe é ouro, é ele que diz se o problema é credencial ou endereço

2. Use o /mcp dentro da sessão

Com o Claude Code aberto, roda:

/mcp

O /mcp checa e gerencia os servidores já adicionados e mostra o status deles ali mesmo, sem tu sair pra outro terminal

3. Abra a configuração de um servidor específico

Quando algo está estranho em um servidor só, vai direto nele:

claude mcp get <nome>

Ele mostra os detalhes daquele servidor, incluindo a configuração

É o jeito rápido de descobrir que aquele header foi salvo com um espaço a mais, por exemplo

Erros comuns ao adicionar um servidor MCP e como resolver

Sintoma: ! Needs authentication

Causa: o Claude Code marca um servidor remoto como precisando de autenticação quando o servidor responde 401 Unauthorized ou 403 Forbidden

Solução: concluir o login, ou em sessão interativa pelo /mcp, ou pela CLI:

claude mcp login <nome>

Sintoma: ✘ Failed to connect com 401 no detalhe

Aqui vale a observação, porque o 401 aparece nos dois casos e isso confunde: o que muda é o status que o claude mcp list mostra na frente, e é ele que decide a tua próxima ação

Causa: um servidor com credencial errada aparece como falho, e o detalhe da linha traz o status HTTP devolvido, por exemplo 401. Como a config foi salva sem validação do token, o erro de digitação só apareceu agora

Solução: se o status é Needs authentication, o caminho é login. Se é Failed to connect com 401 no detalhe, o caminho é outro: revisa o header que tu salvou e recria o registro com a credencial certa

Sintoma: opção rejeitada ou nome lido errado

Causa: quebra de ordem. Opção depois do nome, ou nome grudado logo após o –env (e aí a CLI lê o nome como mais um par KEY=value)

Solução: remonta a linha na ordem opções, nome, destino, e garante outra opção entre o –env e o nome

Sintoma: as flags do servidor somem ou viram erro do Claude Code

Causa: falta do separador — no registro de servidor stdio

Solução: coloca o — antes do comando do servidor, assim tudo depois dele passa intacto pro processo

Quando nada resolve

Limpa e refaz, é mais rápido que caçar vírgula:

claude mcp remove <nome>

E se a suspeita for de algo mais amplo que aquele servidor, roda o /doctor dentro do Claude Code

Ele faz uma checagem automática da instalação, das configurações, das extensões e do uso de contexto

Como prevenir: monta sempre a linha na ordem opções, nome, destino, e usa ${VAR} pra não digitar segredo na mão

Escopo local, project ou user: onde registrar cada servidor

Lembra que lá no começo eu falei que o arquivo depende do escopo? Então, é aqui que isso se resolve

Sem tu pedir nada, o claude mcp add registra o servidor no escopo local, que é privado a você e ativo só no projeto atual

Mas existem três escopos, e a flag –scope é quem escolhe:

Repara que não é um arquivo só: escopo project vai pro .mcp.json do repositório, e os escopos user e local ficam no ~/.claude.json

E como a flag é opção, ela também entra antes do nome do servidor, junto com o –transport

Na prática o raciocínio é esse:

• local pra experimento, servidor que tu está só testando naquele repo
• project pro servidor que o time inteiro precisa, porque o .mcp.json vai junto com o repositório
• user pro teu daily driver, aquele servidor que tu quer em qualquer projeto sem registrar de novo

Alternativas ao claude mcp add: JSON e edição manual

Nem sempre a linha única é o melhor caminho, e tem saída oficial pra isso

Configuração inteira em JSON

Quando o servidor pede vários headers, a linha começa a virar um monstrinho

Aí compensa usar o comando que aceita a config em JSON:

claude mcp add-json <nome> '{"type":"http","url":"...","headers":{...}}'

Editando o .mcp.json na mão

Editar o .mcp.json diretamente e escrever a entrada JSON à mão é alternativa suportada

É o caminho natural quando tu quer versionar a configuração com o time e revisar em pull request, igual qualquer outro arquivo do repo

Autenticação além do token estático

A especificação MCP suporta OAuth 2.1 para autorização, então nem todo servidor vai depender de um header colado na mão

E pra esquemas fora do OAuth, tipo Kerberos ou tokens de vida curta, existe o headersHelper: o Claude Code roda o comando que tu indicar e mescla a saída nos headers da conexão

Os detalhes desses modos estão na documentação de MCP do Claude Code

Conclusão

O fluxo inteiro cabe em três movimentos, beleza?

Monta a linha na ordem certa (opções, nome, destino, e o separador — quando for stdio), roda o claude mcp add, e confere com claude mcp list e com /mcp dentro da sessão

Se eu fosse sugerir um próximo passo, seria esse: começa pelo servidor remoto de documentação, aquele exemplo http oficial, porque é o registro mais simples que existe e te dá a leitura de status sem credencial no meio

Depois que o ✔ Connected aparecer, aí sim parte pro stdio com credencial, que é onde moram os errinhos de ordem

E se tu ainda está decidindo o formato da tua stack antes de plugar tudo, o papo sobre harness de plugins e agente de terminal ajuda a escolher onde investir esse tempo

até o próximo post! 😀