Claude Code MCP: o que é e como conectar ferramentas

O que é MCP no Claude Code?

MCP, ou Model Context Protocol, é um padrão aberto criado pela Anthropic que conecta o Claude Code a ferramentas e dados externos, como bancos de dados, repositórios, APIs e serviços de anúncios. Cada conexão é feita por um servidor MCP, que expõe ações que o Claude Code pode chamar durante a tarefa, com a sua aprovação.

Sem MCP, o Claude Code trabalha com o que está na pasta do projeto e com os comandos que consegue rodar no terminal. Com MCP, ele ganha acesso estruturado a fontes de fora: pode ler o esquema real de um banco, consultar as issues de um repositório ou buscar métricas de uma conta de anúncios. Isso troca suposição por dado verdadeiro.

O protocolo é aberto, então qualquer empresa ou desenvolvedor pode criar um servidor. Há servidores oficiais mantidos pelos próprios serviços, servidores da comunidade e servidores internos que uma empresa escreve para expor as próprias ferramentas. O Claude Code se conecta a todos da mesma forma. Essa padronização é o que torna o ecossistema tão amplo.

• MCP significa Model Context Protocol, um padrão aberto de integração.
• Servidor MCP é a ponte que expõe ações e dados de uma ferramenta.
• O Claude Code passa a usar essas ações como ferramentas durante a tarefa.
• As ações continuam sujeitas às permissões e aprovações que você define.

Como o MCP funciona por baixo dos panos

A arquitetura tem dois lados. O Claude Code atua como cliente: descobre quais servidores estão configurados, pergunta a cada um quais ferramentas oferecem e decide quando chamar cada uma. O servidor recebe a chamada, executa a ação no serviço de destino, como uma consulta SQL ou uma leitura de API, e devolve o resultado em formato estruturado.

Um servidor pode rodar localmente, iniciado por um comando no seu computador, ou remotamente, acessado por uma URL. Servidores locais costumam ser pacotes executados com npx ou um script próprio. Servidores remotos geralmente pedem autenticação, muitas vezes por login no navegador, e são mantidos pelo próprio fornecedor do serviço. Os dois tipos aparecem da mesma forma para o Claude Code.

• Cliente: o Claude Code, que escolhe quando usar cada ferramenta.
• Servidor local: iniciado por um comando, comum em pacotes npm e scripts próprios.
• Servidor remoto: acessado por URL, com autenticação do fornecedor.
• Credenciais ficam na configuração do servidor, não no código do projeto.

Passo a passo para adicionar um servidor MCP no Claude Code

O caminho mais direto é o próprio comando do Claude Code no terminal. Com claude mcp add você registra um servidor informando um nome e o comando que o inicia, ou a URL, no caso de servidores remotos. O comando claude mcp list mostra o que está configurado, e claude mcp remove tira um servidor que não é mais usado.

Também é possível escolher o escopo da configuração. Um servidor pode valer só para você naquele projeto, para todos os seus projetos ou para a equipe inteira, quando fica registrado num arquivo .mcp.json na raiz do repositório. Dentro de uma sessão, o comando /mcp mostra o status de cada servidor e conduz a autenticação quando ela é necessária. A documentação oficial traz as opções atualizadas.

• Passo 1: escolha o servidor, de preferência o oficial do serviço que você quer conectar.
• Passo 2: registre com claude mcp add, informando nome e comando ou URL.
• Passo 3: defina credenciais como variáveis de ambiente, fora de arquivos versionados.
• Passo 4: abra uma sessão e use /mcp para conferir se o servidor está conectado.
• Passo 5: faça um pedido simples de leitura para validar antes de qualquer escrita.

Casos de uso reais de MCP com Claude Code

O uso mais comum é conectar um banco de dados, como Postgres ou Supabase. Com o esquema real à vista, o Claude Code escreve consultas e migrações que batem com as tabelas existentes, em vez de inventar nomes de colunas. Outro uso frequente é o GitHub: ler issues, revisar pull requests e navegar pelo histórico sem sair da sessão.

Em marketing, o MCP oficial da Meta permite que o Claude Code consulte métricas e prepare campanhas na conta de anúncios a partir de instruções em português. Na ZX LAB, essa integração está no produto Tráfego Pago Automatizado, em que toda campanha criada nasce pausada e quem revisa e publica é a pessoa. Empresas também criam servidores internos para expor CRM, webhooks e painéis.

• Banco de dados: leitura do esquema e das tabelas antes de escrever consultas.
• GitHub: issues, pull requests e histórico do repositório dentro da sessão.
• Meta Ads pelo MCP oficial da Meta: métricas, relatórios e campanhas que nascem pausadas.
• Servidor interno: CRM e APIs da empresa expostos de forma padronizada.
• Documentação e arquivos: acesso controlado a fontes fora da pasta do projeto.

Comparativo: MCP, script com API direta ou copiar e colar dados

Há três formas de dar dados externos ao Claude Code. A mais simples é copiar e colar o conteúdo no pedido, o que funciona para algo pontual. A segunda é pedir que ele escreva um script que chama a API do serviço e roda no terminal. A terceira é o MCP, que transforma a integração numa ferramenta reutilizável em todas as sessões.

Cada abordagem tem seu lugar. Copiar e colar é imbatível para uma consulta única. O script com API direta dá controle total e serve quando o serviço não tem servidor MCP. O MCP ganha quando a mesma integração é usada com frequência, por várias pessoas ou em várias tarefas, porque padroniza o acesso e as credenciais.

• Esforço inicial — copiar e colar: nenhum; script: médio; MCP: baixo com servidor pronto, alto se precisar criar um.
• Reaproveitamento — copiar e colar: nenhum; script: por projeto; MCP: em todas as sessões configuradas.
• Dados atualizados — copiar e colar: só o que foi colado; script e MCP: consulta no momento.
• Controle de credenciais — copiar e colar: risco de colar segredo no pedido; script e MCP: credenciais em variáveis de ambiente.
• Melhor uso — copiar e colar: dúvida pontual; script: serviço sem servidor MCP; MCP: integração recorrente.

Segurança e permissões ao usar MCP

MCP amplia o que o Claude Code consegue tocar, e isso exige cuidado proporcional. Um servidor com acesso de escrita a um banco de produção pode alterar dados reais. A regra prática é começar com acesso de leitura, validar o comportamento e só então liberar escrita, preferencialmente num ambiente de teste antes da produção.

A origem do servidor também importa. Servidores oficiais, mantidos pelo próprio fornecedor, merecem mais confiança do que pacotes desconhecidos, principalmente porque recebem suas credenciais. Tokens e chaves nunca devem ir para um repositório público; mantenha-os em variáveis de ambiente e em arquivos ignorados pelo Git. Revogue credenciais que não estão mais em uso.

• Comece com acesso somente leitura.
• Prefira servidores oficiais e mantidos.
• Nunca versione tokens; use variáveis de ambiente.
• Continue aprovando as ações do Claude Code, sobretudo as que alteram dados ou gastam verba.
• Use credenciais com o menor escopo de permissão possível.

Erros comuns e como resolver

A maior parte dos problemas com MCP é de configuração, não do Claude Code. Comando de inicialização errado, pacote que não foi encontrado, variável de ambiente ausente ou token sem a permissão necessária respondem por quase tudo. O comando /mcp dentro da sessão é o primeiro lugar para olhar, porque mostra quais servidores conectaram e quais falharam.

Outro erro frequente é conectar servidores demais. Cada servidor adiciona ferramentas que o Claude Code precisa considerar, e excesso de opções pode deixar as decisões menos precisas. Mantenha conectados os servidores que o projeto realmente usa e desative o restante. Com menos ferramentas disponíveis, as escolhas do Claude Code tendem a ficar mais certeiras e fáceis de acompanhar.

• Servidor não aparece: confira o nome, o comando e o escopo da configuração.
• Falha de autenticação: refaça o login pelo /mcp ou revise o token.
• Permissão negada: o token não tem o escopo necessário para aquela ação.
• Respostas confusas: reduza o número de servidores conectados ao mesmo tempo.