Oi, eu sou a Lena. Algo fez sentido para mim há algumas semanas, e eu tenho tentado descobrir por que demorou tanto para acontecer.

Eu estava usando Claude Code regularmente — executando comandos shell, editando arquivos, revisando refatorações. Útil, mas ainda meio isolado. Então conectei um servidor GitHub MCP e pedi para ele revisar um pull request, verificar erros relacionados no Sentry e atualizar o ticket do Jira. Uma sessão. Três serviços. Funcionou.

Foi então que parou de parecer apenas um terminal inteligente e começou a parecer algo mais componível. Este guia é o que eu gostaria de ter tido antes de passar duas horas lendo documentação fragmentada e issues do GitHub para chegar lá.

Como o MCP Funciona Dentro do Claude Code

Claude Code é um cliente MCP. Essa distinção importa. Por si só, ele pode ler arquivos, executar comandos bash, buscar código e chamar a API da Anthropic. Isso já é muito. Mas ele não consegue acessar seus repositórios do GitHub, suas tabelas do Postgres ou seus frames no Figma sem algo que os conecte.

Esse algo é o MCP — um padrão open source para integrações de ferramentas de IA. Quando você adiciona um servidor MCP, o Claude Code obtém acesso a novas ferramentas: consultar um banco de dados, ler tickets do Jira ou interagir com serviços externos.

Como o Claude Code lida com chamadas de ferramentas

Quando o Claude Code decide que precisa chamar uma ferramenta MCP, ele não a executa imediatamente. O Claude Code mostra uma solicitação de permissão antes de chamar qualquer ferramenta MCP — exibindo o nome da ferramenta e seus argumentos de entrada para que você possa revisar o que ela está prestes a fazer antes de ser executada.

Os nomes das ferramentas seguem um formato estruturado: mcp__<server-name>__<tool-name>. Então, a ferramenta de leitura do servidor de sistema de arquivos se torna mcp__filesystem__read_file. Essa convenção de nomes importa se você estiver pré-aprovando ferramentas em ambientes headless ou CI.

O que o MCP adiciona que as ferramentas nativas não fazem

As ferramentas nativas do Claude Code lidam bem com ambientes locais. O que elas não fazem: acessar serviços externos, consultar bancos de dados ou puxar informações de rastreadores de issues. O MCP amplia esse alcance conectando-o a ferramentas e serviços externos — cada servidor oferece ao Claude Code um novo conjunto de capacidades: consultar um banco de dados, criar uma issue no GitHub, executar um teste de navegador ou obter tokens de design do Figma.

A especificação do Model Context Protocol define três primitivas principais: Recursos (dados brutos), Ferramentas (ações) e Prompts (modelos reutilizáveis). Na prática, as ferramentas são com as quais você irá interagir mais frequentemente.

Como Instalar e Configurar Servidores MCP no Claude Code

Encontrando a localização da configuração MCP

Existem dois locais principais onde o Claude Code armazena a configuração MCP:

Escopo do projeto — .mcp.json no diretório do seu projeto, controlado por versão, compartilhado com sua equipe
Escopo do usuário — suas configurações de usuário, disponíveis em todos os projetos

Substituições específicas do projeto também ficam em .claude/settings.local.json e ~/.claude/settings.local.json para configurações locais específicas do usuário.

Para a maioria dos desenvolvedores individuais, o escopo do usuário é o padrão mais prático. Para configurações em equipe, .mcp.json é o que você quer — ele é comitado junto com o repositório.

Adicionando uma entrada de servidor

O método principal é o comando claude mcp add. Servidores HTTP são a opção recomendada para servidores MCP remotos e são o transporte mais amplamente suportado para serviços baseados na nuvem:

Bash

# Remote HTTP server (recommended for cloud services)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Local stdio server (for tools needing direct system access)
claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/user/projects

# User-scoped (available across all projects)
claude mcp add --scope user my-db -- npx -y @my-org/mcp-server-postgres

Uma coisa que confunde as pessoas: todas as opções (--transport, --env, --scope) devem vir antes do nome do servidor. O -- separa o nome do servidor dos argumentos do comando. Se essa ordem estiver errada, os flags serão passados para o processo errado.

Se você estiver no Windows, envolva os comandos npx com cmd /c:

Bash

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Sem o wrapper cmd /c, o Windows não consegue executar npx diretamente e gera "Conexão encerrada."

Verificando a conexão

Após adicionar um servidor, execute:

Bash

claude mcp list

Dentro de uma sessão do Claude Code, use /mcp para abrir o painel de gerenciamento e verificar o status do servidor. Você verá estados conectados, desconectados ou com erro por servidor.

Testando chamadas de ferramentas em uma sessão

Uma vez que um servidor apareça como conectado, basta pedir ao Claude Code para usá-lo. Algo como: *"Leia o arquivo em /home/user/projects/config.json" após adicionar o servidor de sistema de arquivos. Se configurado corretamente, você verá o prompt de permissão aparecer antes que o Claude Code execute.

Vale notar: a configuração MCP muda com as atualizações do Claude Code. A documentação oficial MCP do Claude Code é a referência autoritativa — verifique se o comportamento divergir do que está descrito aqui.

Servidores MCP recomendados para Claude Code

Estes são servidores que vi se comportarem de forma confiável, com base no que está mantido desde o início de 2026. O repositório oficial de servidores MCP no GitHub tem a lista completa — alguns são mantidos pela Anthropic, a maioria é construída pela comunidade.

Sistema de arquivos — O fundamental. Lê, escreve e organiza arquivos locais com limites de diretório configuráveis. Você controla quais diretórios são expostos.

Bash

claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /your/project/path

GitHub — Adicione o servidor MCP do GitHub com um token de acesso pessoal via transporte HTTP:

Bash

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'

Isso dá ao Claude Code acesso a PRs, issues e repositórios. Útil para pedir coisas como "Revise a diferença no PR #234 e deixe comentários inline."

PostgreSQL — Permite que o Claude consulte seu banco de dados diretamente. Defina sua string de conexão como uma variável de ambiente:

Bash

claude mcp add --scope user my-db -- npx -y @modelcontextprotocol/server-postgres
# Set DATABASE_URL in your environment

Pesquisa na web / Fetch — O Firecrawl MCP busca URLs e retorna Markdown limpo. Útil quando o Claude precisa de documentação de API atual ou referências de terceiros que não estão nos dados de treinamento dele.

Context7 — Recupera documentação de bibliotecas específica da versão. Particularmente útil quando você está trabalhando com uma versão de framework para a qual o Claude não tem dados de treinamento limpos.

Raciocínio Sequencial — Não é uma fonte de dados, mas um servidor de raciocínio. Ajuda o Claude a dividir tarefas complexas de refatoração em passos explícitos antes de executá-las.

Um aviso honesto: use servidores MCP de terceiros com cuidado. A Anthropic não verificou a correção ou segurança de todos os servidores MCP. Tenha cuidado especial com servidores que buscam conteúdo não confiável, pois eles podem expor você a risco de injeção de prompt.

Solução de problemas do MCP no Claude Code

Servidor não aparece

A causa mais comum: problemas de PATH. O Claude Code inicia subprocessos do servidor MCP com um ambiente shell diferente do seu terminal, então ferramentas como node e npx podem não ser encontradas. Se você usa nvm, use caminhos absolutos para o binário do Node ou garanta que o nvm seja carregado em shells não interativos adicionando o bloco de inicialização do nvm ao seu perfil de shell.

Também valide seu JSON. Vírgulas finais, aspas ausentes e barras invertidas não escapadas causam falhas silenciosas — JSON não permite vírgulas finais, e esse é um dos erros mais comuns em arquivos de configuração MCP. Execute sua configuração em um validador JSON antes de reiniciar.

Chamadas de ferramentas retornando erros

Se um servidor conecta mas as chamadas de ferramentas falham, verifique se o formato do nome da ferramenta corresponde: mcp__<server-name>__<tool-name>. Além disso, verifique se as variáveis de ambiente (chaves de API, strings de conexão) estão realmente definidas no seu shell — o Claude Code as herda do ambiente do processo, não do seu arquivo .env automaticamente.

Para problemas com transporte SSE: a variável de ambiente MCP_TIMEOUT não se aplica a conexões SSE — mude para transporte HTTP, que é mais confiável e recomendado pela documentação oficial.

Além do MCP: Tornando o trabalho do Claude Code reutilizável

Aqui está algo com que continuo pensando. MCP resolve o problema de alcance — Claude Code agora pode acessar GitHub, bancos de dados, Slack. Mas cada sessão ainda começa do zero. As correções que Claude descobre, os padrões que ele identifica, as abordagens bem-sucedidas que ele adota — isso não é transmitido automaticamente.

Essa lacuna entre "Claude fez algo útil" e "essa coisa útil agora faz parte de como meu sistema funciona" é real e é separada do que o MCP aborda.

Por enquanto, a solução prática é explícita: use arquivos CLAUDE.md para documentar padrões que Claude deve reutilizar, commit prompts bons junto com o código e trate sessões de Claude Code bem-sucedidas como algo que vale a pena capturar — não apenas consumir.

FAQ

Como adicionar servidores MCP ao Claude Code?

Execute claude mcp add com a flag de transporte apropriada. Para serviços remotos, use --transport http. Para ferramentas locais, use --transport stdio. Defina o escopo do servidor para seu projeto com --scope project ou para seu perfil de usuário com --scope user. A sintaxe completa e exemplos estão na documentação oficial do Claude Code MCP.

Onde fica o arquivo de configuração MCP no Claude Code?

As configurações de escopo do projeto estão em .mcp.json na raiz do projeto. Configurações de escopo de usuário estão nas configurações de usuário do Claude Code. Você também pode editar ~/.claude.json diretamente para configurações mais complexas — apenas valide o JSON antes de reiniciar.

Quais servidores MCP funcionam melhor com o Claude Code?

Para a maioria dos desenvolvedores: o servidor MCP do GitHub e o servidor de sistema de arquivos cobrem os casos de maior frequência. Adicione PostgreSQL se você consultar bancos de dados regularmente. Context7 vale a pena configurar para trabalhos com muita documentação. Sequential Thinking ajuda com refatorações complexas de múltiplos passos. Comece com um ou dois, verifique se conectam corretamente e depois expanda.

Vou continuar acompanhando como essa pilha evolui. A lista acima reflete o que realmente é mantido e utilizável no início de 2026 — não o que soa bem na teoria.