Guia

Como conectar servidores MCP ao Claude Code

Servidores MCP dão ao Claude Code acesso a ferramentas fora do seu código, como um sistema de controle de issues, um banco de dados ou uma ferramenta de design. Este guia mostra os comandos para adicionar um, onde a configuração fica salva, como fazer login e como saber se está funcionando.

Atualizado em 30 de outubro de 2026

Resposta rápida: para um servidor remoto, rode claude mcp add --transport http name https://server/mcp; para um local, rode claude mcp add name -- command args. Acrescente --scope user para usá-lo em todos os projetos ou --scope project para compartilhá-lo pelo .mcp.json. Depois abra o Claude Code, digite /mcp para fazer login se for preciso e confirme que o servidor aparece como conectado.

Os comandos abaixo seguem a documentação do Claude Code da Anthropic em outubro de 2026. Você roda os comandos claude mcp no seu terminal normal, não dentro de uma sessão do Claude Code.

Adicione um servidor remoto (o mais comum)

Um serviço hospedado fornece um endereço web para o seu servidor MCP, que você encontra nas instruções de configuração dele. A Anthropic recomenda o transporte HTTP para esses casos.

No terminal, entre com cd no projeto em que vai usá-lo.
Rode claude mcp add --transport http notion https://mcp.notion.com/mcp, trocando pelo seu nome e endereço. O nome é o que você vai ver nas listas e no /mcp.
Se o serviço usa uma chave de API em vez de login, passe-a como cabeçalho: --header "Authorization: Bearer your-token".

Servidores mais antigos podem oferecer só SSE, que está obsoleto. As versões recentes do Claude Code tentam HTTP primeiro e recorrem ao SSE sozinhas; nas versões antigas, use --transport sse.

Adicione um servidor local

Um servidor local (stdio) é um programa que roda no seu computador, muitas vezes iniciado com npx.

Escreva primeiro as opções do Claude, depois -- e então o comando do próprio servidor: claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server.
O Claude Code repassa tudo o que vem depois de -- direto para o programa do servidor. Sem o separador, opções destinadas ao servidor (como -y) são lidas como opções do Claude Code.
Quando usar --env, coloque outra opção entre ele e o nome do servidor, como no exemplo, senão o nome é lido como mais uma variável.

Escolha um escopo

Escopo	Onde funciona	Salvo em
`local` (padrão)	Neste projeto, só para você	`~/.claude.json`, sob o caminho do projeto
`project`	Neste projeto, para todos que o clonarem	`.mcp.json` na raiz do projeto (faça commit dele)
`user`	Em todos os seus projetos	`~/.claude.json`

Escolha user para ferramentas que você quer em todo lugar, como seu app de notas, e project para ferramentas de que o time inteiro precisa em um repositório. Se um mesmo servidor estiver definido em vários lugares, o Claude Code se conecta uma vez, nesta ordem de prioridade: local, projeto, usuário, depois servidores de plugins e, por fim, conectores do claude.ai. Os três escopos são comparados pelo nome; servidores de plugins e conectores contam como duplicados quando apontam para o mesmo endereço ou comando. A entrada vencedora é usada inteira; os campos não são combinados.

Não coloque segredos diretamente em um .mcp.json compartilhado. Ele aceita variáveis como ${API_KEY} ou ${API_BASE_URL:-https://api.example.com}, que cada pessoa define no próprio ambiente.

Faça login em um servidor que exige conta

Inicie o Claude Code com claude.
Digite /mcp. O painel lista os servidores em que você ainda precisa fazer login.
Selecione o servidor e siga o login no navegador. O token fica guardado no seu computador e é renovado para você.
Outra opção: no seu shell, rode claude mcp login name. Para sair, use claude mcp logout name.

Alguns serviços exigem que você registre um app com eles antes. Nesse caso, adicione o servidor com --client-id, --client-secret (você vai ser solicitado a digitá-lo) e, se a configuração deles pedir um redirecionamento fixo, --callback-port.

Confira se funciona

claude mcp list mostra cada servidor com seu status: Connected (conectado), Needs authentication (precisa de autenticação), Failed to connect (falha ao conectar), Pending approval (aguardando aprovação) ou Disabled for this project (desativado neste projeto).
claude mcp get name mostra os detalhes de um servidor, incluindo o erro HTTP quando ele falha.
Dentro de uma sessão, /mcp mostra o mesmo status e permite reconectar.
Por fim, peça ao Claude algo que só esse servidor consegue fazer, como "list my open Linear issues" (liste minhas issues abertas no Linear).

Remova um servidor com claude mcp remove name.

Bom saber

Servidores de projeto pedem permissão antes: na primeira vez que uma sessão encontra servidores no .mcp.json de um repositório, o Claude Code pede que você os aprove. Desfaça suas escolhas com claude mcp reset-project-choices. Só aprove servidores de repositórios em que você confia.
As permissões continuam valendo: cada chamada a uma ferramenta MCP pode pedir sua confirmação como qualquer outra ferramenta; veja como gerenciar permissões no Claude Code.
Resultados grandes: o Claude Code avisa quando uma ferramenta retorna mais de 10.000 tokens e limita a saída a 25.000 por padrão. Aumente o limite com a variável de ambiente MAX_MCP_OUTPUT_TOKENS.
Plugins: alguns plugins trazem os próprios servidores MCP, então instalar um plugin pode ser um caminho mais fácil; veja como instalar plugins no Claude Code.

Se não funcionar

Failed to connect: rode claude mcp get name para ver o erro, confira a URL e depois rode /mcp reconnect all em uma sessão (versões recentes) para tentar de novo.
Um servidor local lento estoura o tempo na inicialização: inicie o Claude Code com um limite maior, como MCP_TIMEOUT=10000 claude (em milissegundos).
"has a url but no type": falta "type": "http" em uma entrada JSON de servidor remoto.
A chave de API é recusada: o Claude Code avisa quando há espaços ou quebras de linha no início ou no fim de um cabeçalho. Adicione o servidor de novo com o token colado sem sobras.

Fontes

Claude Code user FAQ (Central de Ajuda do Claude, conferido em 30 de outubro de 2026)
Connect Claude Code to tools via MCP (Claude Code Docs, conferido em 30 de outubro de 2026)

Perguntas frequentes

Isso é o mesmo que os conectores do claude.ai?

São coisas relacionadas, mas configuradas separadamente. Os conectores do claude.ai também podem ser carregados no Claude Code, mas ficam por último na prioridade: se um servidor que você adicionou com claude mcp add aponta para o mesmo endereço, o seu é usado. Veja nosso guia de conectores do Claude para os apps web e desktop.

Remover um servidor me desconecta do serviço?

Não totalmente. claude mcp remove apaga o login guardado no seu computador, mas não o revoga. Rode claude mcp logout name antes se quiser que o token seja revogado.

Posso adicionar um servidor a partir de um trecho JSON?

Sim. claude mcp add-json name seguido da configuração JSON funciona. Para um servidor remoto, inclua "type": "http" no JSON, senão ele é tratado como um comando local e falha.