Como adicionar um servidor MCP ao Claude Code: comandos, escopos e soluções

O jeito comum de conectar o Claude Code a uma ferramenta é ler três páginas de configuração diferentes, copiar um comando ligeiramente errado para o seu sistema e não entender por que nada aparece. O processo de verdade é um comando e uma conferência, desde que você saiba qual tipo de servidor está adicionando.

Este guia traz os comandos para os três tipos de servidor, explica os escopos que decidem quem recebe o servidor e cobre login, segurança e as soluções para o que dá errado. Se o MCP é novidade para você, comece por O que é MCP?.

O que você precisa

Conecte um servidor quando você se pegar copiando dados de outra ferramenta para o chat. Depois de conectado, o Claude pode ler daquele sistema e agir nele diretamente.

Três tipos de servidor

O comando que você usa depende de como o servidor se conecta a você.

Servidor HTTP remoto

A forma básica é a mesma para qualquer serviço:

claude mcp add --transport http <name> <url>

Um exemplo real conecta o Notion:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Se o servidor exigir um token, passe-o como cabeçalho:

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

Servidor SSE remoto (obsoleto)

O método SSE é obsoleto, então use HTTP quando o serviço oferecer. Se um serviço só tiver SSE, o comando usa outro transporte:

claude mcp add --transport sse asana https://mcp.asana.com/sse

Servidor stdio local

Um servidor stdio é um programa que roda na sua própria máquina, iniciado pelo Claude Code. A forma básica tem um travessão duplo, e tudo o que vem depois dele é o comando que inicia o servidor:

claude mcp add [options] <name> -- <command> [args...]

Um exemplo que adiciona um servidor do Airtable com uma chave de API:

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

Confira se funcionou

Depois de adicionar um servidor, confira pelo terminal ou de dentro do Claude Code.

$ claude mcp list$ claude mcp get notion$ claude mcp remove notion

Dentro de uma sessão, digite /mcp para ver o status de cada servidor. Você verá um de três estados: conectado, precisa de autenticação ou falha ao conectar.

Entre com OAuth

Muitos servidores na nuvem usam OAuth 2.0, o fluxo de "entrar com a sua conta". O caminho mais simples tem dois passos.

Pelo shell, você também pode rodar claude mcp login <name> e claude mcp logout <name>. Os tokens são guardados com segurança e renovados automaticamente. Para revogar o acesso, use Clear authentication (limpar autenticação) no menu do /mcp.

Escopos: quem recebe o servidor

Ao adicionar um servidor, você escolhe o escopo dele. O escopo decide quais projetos o enxergam e se a sua equipe o compartilha.

Escolha um com a flag --scope:

# Project scope: shared with your team
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# User scope: available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Um servidor no escopo de projeto grava um arquivo .mcp.json na raiz do projeto, que você inclui no commit para que todos recebam a mesma conexão:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Se o mesmo nome de servidor aparece em mais de um escopo, o Claude Code conecta uma vez só, usando a definição da fonte de maior precedência: primeiro o local, depois o de projeto, depois o de usuário.

Quando você abre um projeto que tem um .mcp.json de outra pessoa, o Claude Code pede a sua aprovação antes de usar os servidores dele numa sessão interativa. Para zerar essas escolhas de aprovação, rode claude mcp reset-project-choices.

Servidores populares que você pode adicionar hoje

Estes exemplos vêm da documentação oficial. Leia sempre a página do próprio serviço para ver o endereço atual.

No caso do banco de dados, repare no nome de usuário: readonly. Dê ao Claude uma conta de banco que só pode ler. Essa única escolha evita o erro mais caro que você poderia cometer.

Você também pode explorar os conectores revisados no diretório da Anthropic, em claude.ai/directory. E se você adicionou um conector no claude.ai, ele já está disponível no Claude Code quando você entra com a sua conta do Claude.

Fique seguro

Um servidor MCP dá ao Claude acesso a um sistema, e alguns servidores buscam conteúdo de fora, como páginas web ou tickets escritos por desconhecidos.

Esse último ponto está ligado a quanto o Claude faz sem perguntar. Veja Modos de permissão e modo plan do Claude Code, explicados para decidir isso.

Dentro do Claude Tutorial

Confiar numa ferramenta é uma decisão, não um padrão

Avaliar quais sistemas merecem acesso, e para quais ações, é uma habilidade que vale muito além do código, e o app a pratica com cenários reais.

Em breve

Baixe naApp Store

DISPONÍVEL NOGoogle Play

Limites e ajustes

Dois limites ajudam a explicar comportamentos que, de outro modo, parecem estranhos.

• Resultados grandes. O Claude Code mostra um aviso quando a saída de uma ferramenta passa de 10.000 tokens e limita a saída a 25.000 tokens por padrão. Para aumentar o limite, defina a variável MAX_MCP_OUTPUT_TOKENS, por exemplo MAX_MCP_OUTPUT_TOKENS=50000.
• Servidores lentos. Para mudar quanto tempo o Claude Code espera um servidor iniciar, defina MCP_TIMEOUT. Por exemplo, MCP_TIMEOUT=10000 claude permite dez segundos.

A busca de ferramentas vem ligada por padrão, para que o seu contexto não se encha com a descrição de todas as ferramentas de uma vez. Rode /context para ver o que está ocupando espaço.

Quando não funciona

Quando nada disso resolver, peça ajuda ao Claude Code: cole o erro e pergunte o que ele significa. Rodar /doctor também confere a sua configuração.

Perguntas frequentes

Como adiciono um servidor MCP ao Claude Code?

Rode claude mcp add --transport http <name> <url> para um servidor remoto, ou claude mcp add <name> -- <command> para um local. Depois rode /mcp dentro do Claude Code para ver o status e entrar na conta.

Onde o Claude Code guarda os servidores MCP?

Os servidores de escopo local e de usuário ficam em ~/.claude.json. Os de escopo de projeto ficam num arquivo .mcp.json na raiz do projeto, que você pode incluir no commit.

Qual a diferença entre os escopos local, de projeto e de usuário?

O local vale para o projeto atual e só para você. O de projeto vale para o projeto atual e é compartilhado com a equipe. O de usuário vale para todos os seus projetos e só para você.

Como removo um servidor MCP?

Rode claude mcp remove <name>. Para sair de um servidor sem removê-lo, use claude mcp logout <name>.

O que significa o travessão duplo no claude mcp add?

Ele separa as opções do próprio Claude Code do comando que inicia o servidor. Tudo o que vem depois é repassado ao servidor sem alteração.

Os servidores MCP são seguros?

Só tão seguros quanto os servidores que você escolhe e o acesso que você dá. Use servidores confiáveis, contas de banco somente leitura e um modo de permissão em que você veja o que o Claude faz.

Posso usar no Claude Code os conectores do meu claude.ai?

Sim. Os conectores que você adiciona no claude.ai ficam disponíveis no Claude Code, no terminal e nas sessões na nuvem, quando você entra com a sua conta do Claude.

Seu checklist de MCP no Claude Code

Continue lendo

• O que é MCP? O Model Context Protocol explicado de forma simples para entender a ideia por trás.
• Como adicionar conectores no Claude: diretório, URL personalizada e segurança para o mesmo assunto nos apps do Claude.
• Boas práticas do Claude Code: hábitos que dão melhores resultados para trabalhar bem depois que as ferramentas estiverem conectadas.
• CLAUDE.md explicado: ensine o seu projeto ao Claude Code uma vez só para dizer ao Claude como usar as ferramentas conectadas no seu projeto.