Publicado originalmente em heycc.cn. Esta é uma cópia espelhada — a versão canônica é mantida atualizada na fonte.

Como Configurar um Servidor MCP no Claude Code (Guia de 2026)

Por padrão, o Claude Code só conhece o que está no seu repositório e o que você cola no chat. No momento em que você se vê copiando um ticket de rastreador de problemas, uma pilha de rastreamento de monitoramento ou um resultado de consulta de banco de dados para o prompt, você encontrou esse obstáculo. O Protocolo de Contexto do Modelo (MCP) é como você o derruba. MCP é um padrão de código aberto para integrações de ferramentas de IA, e um servidor MCP dá ao Claude Code acesso direto e estruturado às suas ferramentas, bancos de dados e APIs, em vez de trabalhar a partir do que você cola manualmente.

Um servidor stdio que funciona perfeitamente no macOS e falha no laptop de um colega com Windows; um servidor de projeto que silenciosamente substitui aquele que você definiu; um token no cabeçalho errado que faz o Claude relatar uma conexão morta em vez de solicitar OAuth. Esses são os detalhes específicos à frente — os comandos, o modelo de configuração e os modos de falha que realmente atrapalham as pessoas. Os detalhes sensíveis à versão foram verificados contra a referência oficial do MCP do Claude Code e a especificação da arquitetura do MCP em 2026-06-28, ambos vinculados em Fontes.

Como o MCP realmente funciona

O MCP usa uma arquitetura cliente-servidor. O host MCP (Claude Code, neste caso) inicia um cliente MCP por servidor, e cada cliente mantém uma conexão dedicada com seu servidor. A camada de dados fala JSON-RPC 2.0 por baixo, e cada servidor pode expor até três primitivas principais:

• Ferramentas - funções executáveis que Claude pode chamar (criar um PR, executar uma consulta).
• Recursos - dados contextuais que Claude pode ler (arquivos, registros, respostas de API).
• Prompts - modelos de interação reutilizáveis que o servidor define, que aparecem no Claude Code como comandos /mcp__servername__promptname.

Os servidores se comunicam com o Claude Code através de um dos dois transportes. stdio executa um processo local na sua máquina e se comunica através da entrada/saída padrão, o que é ideal para ferramentas que precisam de acesso direto ao sistema. Streamable HTTP usa HTTP POST para mensagens de cliente para servidor com Eventos Enviados pelo Servidor opcionais para streaming, e suporta tokens de portador, chaves de API, cabeçalhos personalizados e OAuth. Também existe um transporte legado SSE, mas ele está obsoleto - a Anthropic aconselha usar servidores HTTP sempre que estiverem disponíveis. (O Claude Code também pode conduzir um transporte WebSocket via configuração JSON, mas HTTP é o padrão correto porque apenas o HTTP suporta OAuth e a flag --transport.)

Esse é o modelo padrão do MCP, e vale a pena saber porque ele explica o resto deste guia: os escopos decidem onde um servidor é definido, os transportes decidem como Claude chega até ele, e as primitivas decidem o que ele pode fazer uma vez conectado.

Escolha seu transporte e escopo primeiro

Antes de digitar qualquer comando, tome duas decisões: qual transporte o servidor usa e em qual escopo ele deve viver. Esta tabela mapeia as escolhas para onde a configuração termina.

Quando o mesmo nome de servidor é definido em mais de um escopo, o Claude Code se conecta uma vez usando a definição de maior precedência: local tem a maior precedência, depois project, depois user. A entrada inteira do escopo vencedor é usada - os campos não são mesclados entre escopos. Na prática, isso significa que uma entrada de servidor local substitui completamente uma entrada project do mesmo nome, em vez de sobrescrevê-la campo por campo. (Servidores fornecidos por plugins e conectores claude.ai ficam abaixo de todos os três escopos nomeados e são correspondidos por endpoint, não por nome.)

Adicione um servidor HTTP remoto

HTTP é o transporte recomendado para servidores remotos. O padrão é:

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

Por exemplo, para conectar o Notion:

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

Se o servidor for uma infraestrutura compartilhada que toda a sua equipe usa, adicione --scope project para que ele fique em .mcp.json e viaje com o repositório:

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

Se um fornecedor documentar apenas um endpoint SSE obsoleto, a sintaxe é claude mcp add --transport sse <nome> <url> - mas prefira HTTP quando ambos existirem.

Adicione um servidor stdio local

Servidores locais executam como um processo filho. O duplo hífen é a parte importante:

claude mcp add [opções] <nome> -- <comando> [args...]

Tudo após -- é passado para o servidor sem alterações, separando as próprias flags do Claude (--transport, --env, --scope) do comando que inicia o servidor. A documentação oficial usa o Airtable como exemplo de stdio, que também mostra como --env injeta credenciais:

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

Um segundo exemplo real da documentação é uma conexão de leitura do Postgres via dbhub:

claude mcp add --env DBHUB_API_KEY=SUA_CHAVE --transport stdio dbhub \
  -- npx -y dbhub-mcp-server