Configurar MCP no Claude Code: adicionar servidores

Para configurar MCP no Claude Code, rode claude mcp add no terminal. Um servidor local é claude mcp add <nome> -- <comando>, um remoto é claude mcp add --transport http <nome> <url>, e --scope decide se o servidor vale só para você neste projeto (local, o padrão), para o time inteiro por meio de um arquivo .mcp.json (project) ou para você em todos os projetos (user). Depois digite /mcp dentro de uma sessão para conferir a conexão e fazer login nos servidores que usam OAuth.

Este guia passa por cada etapa: transportes, o separador --, variáveis de ambiente e headers, escopos, escrever o .mcp.json à mão, os comandos list, get e remove, OAuth, importação do Claude Desktop, timeouts e limites de saída, e o que conferir antes de confiar nos servidores de um projeto. Os comandos vêm da documentação de MCP do Claude Code da Anthropic, em outubro de 2026. Se MCP é novidade para você, comece por o que é um servidor MCP; se quer saber quais servidores adicionar, veja os melhores servidores MCP para programar.

Referência rápida

As opções curtas também funcionam: -t para --transport, -s para --scope, -e para --env e -H para --header.

Escolha o transporte: stdio, HTTP ou SSE

Um servidor MCP chega ao Claude Code de uma de três formas:

Você quase não precisa mais de --transport sse. Desde o Claude Code 2.1.265, claude mcp add --transport http tenta HTTP primeiro e muda sozinho para SSE quando o servidor não aceita HTTP. Em versões mais antigas, passe --transport sse explicitamente.

Adicionar um servidor stdio local

A regra que mais confunde: as opções do próprio Claude Code (--transport, --scope, --env) vêm antes do nome do servidor, e tudo depois de -- é o comando do servidor, repassado sem alteração.

# Forma básica
claude mcp add [opções] <nome> -- <comando> [argumentos...]

# Playwright, rodando com npx
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Um servidor que precisa de uma API key no ambiente
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Sem o --, uma opção do servidor como --port 8080 seria lida como opção do Claude Code e o comando falharia. Outra pegadinha citada na documentação: --env aceita vários pares KEY=value, então se o nome do servidor vier logo depois, ele é lido como mais um par e rejeitado. Coloque outra opção no meio, como --transport stdio, igual ao exemplo acima.

O Claude Code define CLAUDE_PROJECT_DIR no ambiente de cada servidor stdio, assim o servidor encontra a raiz do projeto sem depender do diretório de trabalho.

Adicionar um servidor HTTP remoto

Servidores remotos recebem uma URL em vez de um comando. Adicione headers com --header quando o servidor pedir uma API key ou um bearer token:

# Um servidor hospedado que faz login com OAuth
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Um servidor que usa um token estático
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

O header que você digita aqui fica salvo em texto puro no arquivo de configuração. Para qualquer coisa compartilhada, prefira OAuth ou uma referência ${VAR} no .mcp.json, explicada abaixo.

Se o README do servidor já traz uma definição em JSON, pule as opções e cole com add-json. O comando recebe o objeto que ficaria dentro de mcpServers, não o arquivo inteiro:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Escolha o escopo

Cada claude mcp add grava em um de três escopos:

claude mcp add --transport http stripe https://mcp.stripe.com                      # local
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Regra prática: ferramentas pessoais e tudo que leva suas próprias credenciais vão em user ou local; servidores de que o time inteiro precisa para trabalhar no repo vão em project.

Atenção: “local” aqui não é o .claude/settings.local.json. Servidores MCP locais ficam em ~/.claude.json, na sua pasta de usuário.

Quando o mesmo nome está definido em mais de um lugar, o Claude Code usa o de maior prioridade e não mescla campos: primeiro local, depois project, depois user, depois servidores de plugins e, por último, os conectores do claude.ai. Se dois escopos apontam o mesmo nome para endpoints diferentes, claude mcp list e /mcp avisam.

Escrever o .mcp.json à mão

Um servidor com escopo project é só um arquivo .mcp.json que você pode editar e revisar em pull requests:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR} é substituído pelo valor de uma variável de ambiente, e ${VAR:-default} usa um valor padrão quando ela não existe. A expansão funciona em command, args, env, url e headers, e é assim que você commita o arquivo sem commitar tokens: cada desenvolvedor define API_KEY no próprio shell. Se uma variável faltar e não tiver valor padrão, claude mcp list e /mcp avisam e deixam o texto sem expandir.

Um "timeout" por servidor, em milissegundos, define um limite rígido para as chamadas de ferramenta daquele servidor.

Gerenciar servidores: list, get, remove e /mcp

No shell:

claude mcp list          # todos os servidores, com status de conexão
claude mcp get notion    # detalhes de um servidor, inclusive por que falhou
claude mcp remove notion # remove do escopo onde está

list e get mostram o detalhe do erro com as credenciais ocultas. Um servidor de projeto que você ainda não aprovou aparece como pendente até você abrir o claude no modo interativo e aprová-lo.

Dentro de uma sessão, /mcp é o painel de controle. Ele mostra o status e a quantidade de ferramentas de cada servidor, e no menu de um servidor você pode se autenticar, se reautenticar, limpar a autenticação, reconectar ou desativar o servidor sem apagar a configuração. /mcp reconnect all tenta de novo todos os servidores com falha de uma vez (Claude Code 2.1.284 ou mais recente).

Servidores conectados trazem mais do que ferramentas. Digite @ para referenciar recursos de um servidor ao lado dos seus arquivos, e / para ver os prompts dele, listados como /servidor:prompt (MCP). As ferramentas se chamam mcp__<servidor>__<ferramenta>, e é esse nome que você usa nas regras de permissão e nos matchers de hooks.

Fazer login em servidores OAuth

Muitos servidores hospedados, como Sentry, Notion ou Linear, usam OAuth em vez de um token estático. Adicione o servidor com --transport http e sem header, e depois faça login:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

No Claude Code, rode /mcp, escolha o servidor e clique em Authenticate. O navegador abre, você faz login, e o Claude Code guarda o token e o renova. Também dá para fazer pelo shell, sem abrir uma sessão:

claude mcp login sentry               # abre o navegador
claude mcp login sentry --no-browser  # imprime a URL, para sessões SSH
claude mcp logout sentry              # esquece as credenciais salvas

Execuções headless (claude -p) não conseguem mostrar uma tela de login, então faça login uma vez no modo interativo antes. Alguns servidores exigem uma porta de callback fixa ou um app OAuth pré-registrado; para eles, passe --callback-port, --client-id e --client-secret ao adicionar o servidor. O secret é pedido com entrada mascarada, ou lido de MCP_CLIENT_SECRET no CI.

Importar servidores do Claude Desktop

Se você já configurou servidores no app Claude Desktop, não precisa digitar tudo de novo:

claude mcp add-from-claude-desktop

Uma janela deixa você escolher quais servidores importar. Em outubro de 2026, isso só funciona no macOS e no WSL. Adicione --scope user para importar para a sua configuração de usuário. Nomes de servidor só podem ter letras, números, hífens e underscores, então um servidor do Desktop com espaço no nome é ignorado e reportado, e um nome que já existe ganha um sufixo como server_1.

Solução de problemas

Resultados de texto longos têm um segundo limite: um resultado com mais de 50.000 caracteres é salvo em um arquivo em vez de entrar direto no contexto.

Servidores remotos que caem no meio da sessão são retentados até cinco vezes com intervalo crescente, mas servidores stdio não são retentados automaticamente, então um servidor local que travou precisa ser reconectado pelo /mcp.

O contexto é o outro custo a acompanhar. Nos modelos atuais, o Claude Code usa busca de ferramentas (tool search) por padrão: na inicialização só carrega os nomes das ferramentas e as instruções dos servidores, e as definições completas são carregadas quando o Claude precisa delas. Isso deixa uma lista longa de servidores barata, mas cada servidor ainda é mais uma peça que pode falhar ou ser mal usada, então mantenha a lista curta. Em scripts, --mcp-config <arquivo> carrega servidores extras para uma única execução, e --strict-mcp-config faz o Claude Code usar só esses.

Segurança: servidores de projeto são código do repo

Um .mcp.json em um repo pode iniciar qualquer comando local ou apontar para qualquer URL. É isso que o torna útil para times, e também o motivo de o Claude Code tratá-lo com cuidado:

• Aprovação primeiro. Em uma sessão interativa, o Claude Code pergunta antes de usar servidores com escopo project. claude mcp reset-project-choices limpa suas respostas anteriores.
• Um repo não aprova a si mesmo. Configurações como enableAllProjectMcpServers commitadas no .claude/settings.json do projeto são ignoradas até você confiar na pasta, e o servidor continua pendente. Aprovações das suas próprias configurações de usuário continuam valendo.
• Execuções headless não perguntam. Em claude -p e no Agent SDK não existe a pergunta, então os servidores de projeto carregam sem ela. Para bloquear um servidor em qualquer modo, coloque-o em disabledMcpjsonServers.
• As credenciais ficam em casa. Em url e headers de um servidor remoto, variáveis sensíveis como ANTHROPIC_API_KEY são expandidas como vazias mesmo que estejam definidas, então um projeto não consegue mandar sua chave da Anthropic para o servidor dele sem você perceber.
• Confie tão pouco no que o servidor devolve quanto no que ele executa. A documentação da Anthropic avisa que servidores que buscam conteúdo externo podem expor você a prompt injection. Prefira modos somente leitura e tokens com permissões mínimas.

Antes de aprovar, leia o command, os args e a url de cada servidor do mesmo jeito que você leria um script postinstall. O panorama geral está em segurança de agentes de código com IA.

Quando você usa mais do que o Claude Code

Tudo acima vale por CLI. O Codex guarda seus servidores em ~/.codex/config.toml, o Gemini CLI no próprio settings.json, e cada ferramenta tem seus comandos. Se o Claude Code é o único agente que você usa, claude mcp add e um .mcp.json commitado bastam, e nada aqui exige outra ferramenta.

Se você usa várias CLIs de código, as listas acabam se desencontrando. É para isso que existe o gerenciador de MCP do AgentVera, o app desktop que publica este blog:

• Adicionado uma vez, conectado na inicialização. Você registra servidores stdio, HTTP e SSE no AgentVera, e eles se conectam quando os agentes iniciam: em todos os agentes, nos que você escolher, nos agentes de um grupo ou em um papel de time. Claude Code, Codex e os outros agentes de CLI com suporte a MCP recebem esses servidores.
• Em sintonia com a configuração do Claude Code. Os servidores das configurações do Claude Code e do Codex aparecem com o status deles; você pode importá-los para o AgentVera ou removê-los da CLI, e os servidores do AgentVera também podem ser gravados nas configurações da CLI.
• Um só login, sem tokens em arquivos. Servidores remotos passam pelo gateway do AgentVera, você faz login uma vez no app em um servidor OAuth, e a CLI do agente não guarda nenhum header nem token. Variáveis de ambiente e headers secretos ficam no chaveiro do sistema operacional.
• Custos à vista. Um teste de conexão lista as ferramentas, prompts e recursos de um servidor com um custo aproximado em tokens por ferramenta.

Resumindo

Comece com um servidor de que você realmente precisa, adicionado com claude mcp add no escopo mais restrito que funcione. Confira com claude mcp list ou /mcp, faça login com /mcp ou claude mcp login, e só mova para um .mcp.json commitado quando o time inteiro precisar, com os tokens em referências ${VAR}. Quando algo quebrar, claude mcp get, MCP_TIMEOUT e MAX_MCP_OUTPUT_TOKENS resolvem quase tudo.

Leia mais:

• O que é um servidor MCP?
• Os melhores servidores MCP para agentes de código
• Gerenciador de MCP
• Claude Code como agente