Integração Claude Code MCP: Conecte Ferramentas ao Agente

Última atualização: June 28, 2026

De fábrica, o Claude Code lê e edita arquivos e executa comandos de shell. Ele não consegue ler os issues do seu GitHub, consultar seu banco de dados ou controlar um navegador. O Model Context Protocol (MCP) fecha essa lacuna: é o plug padrão que permite ao agente interagir com ferramentas e dados externos. Este guia mostra os comandos exatos claude mcp add, quando escolher um servidor local versus remoto, como funcionam os escopos, quais servidores vale a pena conectar e as verificações de segurança a serem realizadas antes de confiar em algum.

Resposta rápida: como adicionar um servidor MCP ao Claude Code?

Você registra um servidor com o comando claude mcp add, e então o Claude Code pode chamar suas ferramentas durante uma sessão.

Para um servidor local que roda como processo na sua máquina:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Para um servidor remoto acessado via HTTPS:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

Após adicionar um servidor, execute /mcp dentro do Claude Code para ver seu status de conexão e completar qualquer login OAuth. Use claude mcp list para confirmar o registro. A referência oficial de comandos está em Claude Code MCP docs.

O que é MCP e por que conectá-lo ao Claude Code?

MCP é um protocolo aberto, publicado pela primeira vez pela Anthropic, que define como um cliente de IA e um servidor de ferramentas trocam capacidades. Um servidor anuncia ferramentas (ações que o agente pode realizar), recursos (dados que ele pode ler) e prompts. Qualquer cliente ciente de MCP pode usar qualquer servidor MCP, então um servidor GitHub funciona no Claude Code, em um IDE ou em outro agente sem cola personalizada. A especificação e o registro de servidores estão em modelcontextprotocol.io.

O benefício prático: em vez de colar o corpo de um problema no chat, você conecta o servidor GitHub uma vez e pede ao agente para ler, rotular e responder a problemas diretamente. Para um histórico mais profundo sobre o próprio protocolo, veja nosso MCP explainer, e para a ferramenta completa em contexto, o Claude Code ultimate guide.

Um servidor pode ser um pequeno script stdio que você escreveu, uma imagem Docker ou um endpoint SaaS hospedado por um fornecedor. O Claude Code trata todos eles da mesma maneira assim que falam MCP.

Qual transporte você deve usar: local ou remoto?

Transporte é como o Claude Code alcança o servidor. Servidores locais rodam na sua máquina via stdio; servidores remotos rodam em outro lugar e respondem via HTTP ou SSE. A escolha geralmente segue onde os dados estão localizados.

Use um servidor stdio local quando a ferramenta precisar de arquivos ou serviços no seu laptop, como uma pasta de assets do projeto ou uma instância Postgres em localhost. Use um servidor HTTP ou SSE remoto quando um fornecedor já o hospeda, pois você pula a instalação e recebe atualizações sem tocar na sua config. Servidores remotos quase sempre fazem login através de OAuth, que você aciona no menu /mcp.

Escolhendo um escopo: local, projeto ou usuário

Escopo decide quem vê o servidor e onde a configuração é armazenada. Claude Code suporta três opções, e escolher a correta mantém os segredos fora do seu repo enquanto ainda compartilha servidores seguros com a equipe.

Defina o escopo com a flag --scope, por exemplo claude mcp add --scope project .... O escopo de projeto escreve um .mcp.json versionado, então nunca coloque um token bruto lá; referencie uma variável de ambiente em vez disso. O escopo local é o padrão e o lugar mais seguro para testar um novo servidor antes de se comprometer a compartilhá-lo. Se você também construir Claude Code skills, mantenha o escopo do servidor e o escopo da habilidade consistentes para que um colega de equipe que puxar o repo tenha uma configuração funcional.

Como adicionar um servidor com claude mcp add?

O padrão é o mesmo para todos os servidores: um nome, uma flag de transporte opcional e o comando ou URL. O separador -- marca o início do comando local e seus argumentos.

Adicione um servidor de sistema de arquivos local restrito a uma pasta para que o agente só possa acessar o que você permitir:

claude mcp add filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem ~/projects/my-app

Passe segredos como variáveis de ambiente em vez de codificá-los diretamente:

claude mcp add my-api --env API_KEY=your_key_here -- node ./my-mcp-server.js

Adicione um servidor remoto com seu transporte e URL:

claude mcp add --transport sse linear https://mcp.linear.app/sse

Em seguida, gerencie o que você tem:

• claude mcp list mostra todos os servidores registrados e seu status.
• claude mcp get <name> imprime a configuração de um servidor.
• claude mcp remove <name> desregistra-o.
• /mcp (digitado em uma sessão) mostra o estado de conexão ao vivo e executa OAuth.

Mantenha o uso das flags próximo à documentação oficial; os fornecedores ocasionalmente alteram o nome do pacote ou a URL de um servidor, portanto, copie o valor atual do README próprio do servidor em vez de adivinhar.

Servidores MCP comuns que valem a pena conectar

Comece com um servidor que elimina uma tarefa realmente tediosa, teste-o e depois adicione mais. Estes são os que os desenvolvedores procuram primeiro, e o que cada um desbloqueia.

O Playwright MCP server é o destaque para trabalho front-end: o agente abre sua página, clica por um fluxo e relata o que falhou com uma captura de tela. Um servidor de banco de dados é útil para perguntas de esquema somente leitura, mas escopo-o em um read replica para que uma consulta errante nunca possa escrever. Quando você começa a encadear vários servidores juntos, direcione o trabalho pesado para um worker dedicado usando Claude Code subagents para que a sessão principal permaneça responsiva.

Cenário: conectar um servidor MCP do GitHub para abrir PRs

Suponha que você queira que o agente trie problemas e abra pull requests em um único repositório. O GitHub hospeda um servidor MCP remoto oficial, então você não precisa instalar nada localmente.

1. Registrar o servidor hospedado:

   claude mcp add --transport http github https://api.githubcopilot.com/mcp/
   

2. Digite /mcp no Claude Code, selecione github e conclua o login OAuth em seu navegador. O token permanece com o GitHub; você nunca cola ele em um arquivo.

3. Confirme as ferramentas carregadas com claude mcp list.

4. Agora peça em linguagem simples:

   • "Listar problemas abertos rotulados como bug e resumir os três principais."
   • "Abrir um rascunho de PR de fix/login-redirect para main com uma descrição curta."
   • "Ler o PR #214 e sinalizar qualquer coisa que toque autenticação."

O agente lê os tópicos de problemas, rascunha o corpo do PR e vincula o problema correto, tudo sem que você precise sair do terminal. Conceda primeiro ao app GitHub acesso a um único repositório, revise o que o agente propõe e amplie o acesso somente quando confiar no fluxo. A lista completa de ferramentas do servidor e a opção de auto-hospedagem são documentadas em GitHub MCP server repo.

É seguro conectar um servidor MCP?

Um servidor MCP pode executar código em sua máquina ou agir em suas contas, então trate cada um como se estivesse instalando uma dependência: conecte apenas servidores que você confia. O risco é real porque um servidor malicioso ou com bugs pode exfiltrar arquivos ou tomar ações destrutivas com suas credenciais.

Verifique estes pontos antes de adicionar um servidor:

• Confirme a fonte. Prefira servidores oficiais de fornecedores (GitHub, Sentry) ou os servidores de referência publicados em vez de um pacote desconhecido.
• Leia quais ferramentas ele expõe. Um servidor "ler meus problemas" não deve solicitar acesso de escrita ao seu disco inteiro.
• Escopo apertado. Aponte os servidores de sistema de arquivos para uma pasta de projeto e os servidores de banco de dados para um réplica de leitura.
• Mantenha segredos fora do .mcp.json. Use variáveis de ambiente e nunca commite um token real.
• Conceda o menor privilégio no OAuth. Dê a um aplicativo GitHub um repositório, não toda a sua organização, até que você confie nele.
• Revise as ações antes de aprovar. Leia o PR ou consulte o que o agente propõe; não aprove automaticamente escritas de um novo servidor.

A Anthropic sinaliza o risco de prompt-injection para servidores que buscam conteúdo web não confiável, então tenha extremo cuidado com qualquer servidor que puxe páginas arbitrárias. A orientação de segurança atual está em Claude Code MCP docs.

Solução de Problemas com conexões MCP

A maioria das falhas é de configuração ou autenticação, não do protocolo. Siga estes passos em ordem:

• Servidor não listado: execute novamente claude mcp list. Se estiver faltando, o comando add provavelmente falhou; verifique se há um erro de digitação no separador -- ou no nome do pacote.

• Status mostra falha em /mcp: o processo não conseguiu iniciar. Para servidores stdio, execute o comando bruto (por exemplo, a linha npx) no seu terminal para ver o erro real.

• Falha na autenticação: abra /mcp, selecione o servidor e refaça o fluxo OAuth. Para servidores baseados em token, confirme se a variável de ambiente está definida no shell que iniciou o Claude Code.

• Ferramentas não aparecendo: reinicie a sessão do Claude Code para que ele recarregue as capacidades do servidor e, em seguida, verifique se o escopo é um que o projeto atual pode visualizar.

• Escopo incorreto: um servidor adicionado com --scope local não será exibido para os colegas de equipe; adicione-o novamente com --scope project se ele deve ser compartilhado.

Quando um servidor remoto muda seu URL ou um pacote é renomeado, sua configuração salva fica obsoleta. Puxe o valor atual do README do servidor e adicione-o novamente em vez de editar cegamente.

Principal Conclusão

O MCP transforma o Claude Code de um agente baseado em arquivos e shell em um que se comunica com suas ferramentas reais. Adicione servidores com claude mcp add, escolha stdio para dados locais e HTTP/SSE para serviços hospedados, e defina o escopo por quem deve ver o servidor. Conecte um servidor útil primeiro; o servidor do GitHub é um bom começo, e verifique a fonte e as permissões de cada servidor antes de confiar nele. Mantenha os tokens em variáveis de ambiente, limite o acesso ao sistema de arquivos e ao banco de dados, e revise as ações do agente até que um novo servidor mereça isso.