MCP no Claude Code ainda confunde muita gente que acabou de instalar o ambiente e está tentando entender o que a sigla significa na prática. O conceito é simples, mas a configuração tem detalhes que a documentação cobre de forma dispersa e a maioria dos tutoriais pula.
Se você usa o Claude Code para desenvolvimento e quer conectar o agente a ferramentas externas de verdade, esse post é o ponto de entrada certo.
O que é MCP e por que o Claude Code depende dele
MCP significa Model Context Protocol. É um padrão aberto criado pela Anthropic para definir como um modelo de linguagem se comunica com ferramentas externas durante uma sessão ativa de trabalho.
Sem MCP, o Claude Code funciona dentro do seu projeto de código. Lê arquivos, sugere mudanças, entende o contexto local. Com MCP configurado, você conecta o agente a banco de dados, APIs, sistemas de documentação e praticamente qualquer serviço que tenha um servidor compatível.
Não é mágica. É protocolo. A diferença importa porque entender isso muda como você projeta o que o agente vai conseguir fazer, e o que vai esperar dele no dia a dia.
O que você consegue fazer com um servidor MCP
A forma mais direta de entender é pelo exemplo concreto. Quando você configura o MCP para um servidor de PostgreSQL, o Claude Code consegue consultar o schema, entender as relações entre tabelas e sugerir queries com contexto real, não com base em suposições sobre como seu banco está estruturado.
Outros casos que aparecem muito:
- Acesso a documentação interna via servidor de busca semântica
- Leitura e escrita em ferramentas como Notion, Linear ou Jira
- Execução de comandos em ambiente controlado e auditável
- Integração com APIs proprietárias da empresa
- Acesso a sistemas de arquivos remotos com permissão explícita
Cada servidor MCP expõe um conjunto de tools. O Claude decide, com base no contexto da sessão, quando e como chamar cada uma. Se quiser entender melhor como o modelo usa ferramentas nesse processo, o post sobre como projetar ferramentas que agentes de IA conseguem usar entra em mais detalhe sobre esse mecanismo.
Como instalar e configurar o MCP no Claude Code
O que você precisa antes de começar
O MCP no Claude Code é gerenciado via CLI. Você precisa do Claude Code instalado e, para cada servidor que quiser usar, o runtime correspondente. A maioria dos servidores públicos disponíveis hoje roda em Node.js. Alguns usam Python.
Não precisa saber programar para usar servidores prontos da comunidade. Mas precisa ter esses runtimes no PATH da sua máquina. Se o comando node não responde no terminal, o servidor não vai subir. Confirma isso antes de depurar qualquer outra coisa.
Os comandos para adicionar e listar servidores
O Claude Code tem um subcomando dedicado para gerenciar servidores MCP. Para adicionar o servidor de filesystem:
- claude mcp add filesystem npx @modelcontextprotocol/server-filesystem ~/projetos
- claude mcp list
O primeiro comando registra o servidor com o nome filesystem e aponta para o diretório que você quer expor. O segundo lista todos os servidores configurados. Se o servidor aparecer na lista mas não aparecer nas tools da sessão, provavelmente não está rodando.
Escopo de projeto versus escopo global
Configuração no nível do projeto fica registrada naquele diretório e só ativa quando você abre o Claude Code a partir dele. Configuração global fica disponível em qualquer sessão da máquina.
Para servidores de infraestrutura como banco de dados ou filesystem, o escopo de projeto faz mais sentido. Para servidores de produtividade como Notion ou Linear, o global funciona melhor porque você usa de qualquer contexto de trabalho.
Servidores MCP que valem a pena conhecer primeiro
Tem um catálogo mantido pela comunidade com servidores prontos para uso. Os mais testados e com menos surpresa:
- MCP Filesystem: acesso controlado a diretórios locais. Útil quando você quer que o Claude leia arquivos fora do projeto atual sem dar acesso irrestrito à máquina.
- MCP PostgreSQL: conexão direta ao banco. Funciona bem para exploração de schema, entendimento de estrutura de dados e geração de queries com contexto real.
- MCP GitHub: acesso a repositórios, issues e pull requests. Útil quando o agente precisa de contexto além do código local que está aberto.
- MCP Fetch: permite que o Claude acesse URLs específicas de forma controlada, útil para buscar documentação externa ou verificar o retorno de uma API.
A lista completa e as instruções de cada servidor estão na documentação oficial do Model Context Protocol, mantida pela Anthropic e atualizada com frequência. Vale passar por lá antes de instalar qualquer servidor de fonte desconhecida.
Quando configurar MCP faz sentido (e quando não faz)
Faz sentido configurar MCP quando você usa o Claude Code de forma recorrente em tarefas que precisam de contexto externo real. Quando o agente precisa entender seu banco de dados para ajudar de verdade. Quando trabalha com documentação proprietária que não está no repositório.
Não faz sentido quando você usa o Claude Code de forma pontual, só para revisão de código ou geração de funções isoladas. O overhead de manter servidores rodando e a configuração inicial não compensam para uso casual.
Esse segundo grupo é maior do que parece. Muita gente configura MCP porque parece poderoso, usa uma semana e abandona porque o fluxo não justificava o setup. A mesma lógica vale para usar subagentes no Claude Code: o overhead só faz sentido quando o ganho é real e recorrente, não quando é uma configuração que você mantém só para dizer que tem.
Os erros mais comuns que travam a configuração
Servidor não encontrado: o caminho do executável está errado ou o runtime não está instalado. Confirme isso antes de procurar problema no arquivo de configuração.
Tool não aparece na sessão: o servidor está registrado mas não está rodando. MCP é cliente-servidor. Servidor parado é tool invisível para o agente. Isso explica boa parte dos relatos de "MCP não está funcionando" que aparecem em fóruns e Discord.
Permissão negada no Filesystem: o servidor só acessa o que você autorizar explicitamente no momento do registro. Não é bug, é comportamento esperado de segurança.
Variável de ambiente ausente: muitos servidores precisam de API key ou credencial via variável de ambiente. Se não estiver configurada, o servidor sobe mas falha em todas as chamadas, às vezes sem mensagem de erro clara o suficiente para entender o que está errado.
O que muda depois que o MCP está funcionando
Com MCP configurado, o Claude Code começa a tomar decisões melhores porque tem informação real, não estimada. A diferença fica mais visível em projetos com banco de dados complexo ou com documentação interna que o modelo não teria como inferir pelo código sozinho.
O que não muda: o modelo ainda pode errar. MCP não elimina alucinação, reduz ela nos pontos onde faltava contexto. Para entender como medir a qualidade das respostas nesse tipo de setup, o post sobre avaliação de LLM em produção tem critérios que se aplicam diretamente a esse cenário.
Dúvidas frequentes sobre MCP no Claude Code
MCP funciona no Windows?
Funciona, mas com mais fricção. Caminhos de arquivo, permissões e comportamento do terminal no Windows às vezes causam problemas que no Linux ou macOS não acontecem. Se o servidor não subir ou aparecer erro de caminho, esse costuma ser o motivo. Dá para resolver, mas exige ajuste manual em alguns casos.
Quantos servidores MCP posso ter ativos ao mesmo tempo?
Não tem limite técnico documentado. Na prática, cada servidor adiciona overhead de decisão para o modelo. Quatro a seis servidores relevantes é o suficiente para a maioria dos projetos. Mais do que isso e você começa a confundir o modelo com tools em excesso, o que piora a qualidade das respostas em vez de melhorar.
Preciso saber programar para criar um servidor MCP customizado?
Para usar servidores prontos da comunidade, não precisa. Para criar um servidor customizado para APIs internas da sua empresa, precisa entender o protocolo e implementar o servidor. Para começar, os servidores públicos já cobrem bastante coisa sem precisar escrever uma linha.
Por onde começar sem se perder no setup
MCP no Claude Code é um upgrade prático para quem já usa o ambiente com frequência e sente que o agente às vezes opera no escuro por falta de contexto. Não precisa configurar tudo de uma vez.
Começa por um servidor que resolve uma fricção real que você já sente no fluxo atual. Se o banco de dados é o gargalo, começa pelo servidor de PostgreSQL. Se é documentação, começa por Fetch. Upgrade incremental funciona melhor do que configurar seis servidores no primeiro dia e desistir na segunda semana.
Se você ainda está decidindo qual assistente de código usar antes de investir tempo nesse setup, o post sobre Cursor vs Claude Code em 2025 ajuda a definir se o ambiente faz sentido para o seu fluxo antes de ir fundo na configuração.
- Escolhe um servidor MCP que resolve uma dor real no projeto atual e configura só ele primeiro.
- Testa a integração por pelo menos uma semana antes de adicionar mais servidores ao setup.
- Tem dúvida específica sobre algum passo? Deixa nos comentários.