Até aqui, o Claude Code trabalhou dentro de dois mundos: o sistema de arquivos do seu projeto e o terminal. Neste capítulo você vai aprender a abrir uma terceira porta com o Model Context Protocol, conectando a ferramenta a bancos de dados, ao GitHub, à documentação de bibliotecas, a um navegador e aos sistemas internos da sua empresa, sem perder o controle de permissões que construímos no capítulo seis.
O que é o Model Context Protocol
O Model Context Protocol, abreviado como MCP, é um protocolo aberto criado pela Anthropic para que assistentes de inteligência artificial conversem com sistemas externos de forma padronizada. A ideia é simples: em vez de cada ferramenta inventar sua própria integração, qualquer serviço pode expor um servidor MCP, e qualquer cliente compatível, como o Claude Code, consegue usá-lo. Pense nele como uma tomada universal.
Um servidor MCP pode fornecer três coisas. A primeira são ferramentas, que são ações que o Claude pode executar, como rodar uma consulta em um banco de dados ou abrir uma página no navegador. A segunda são recursos, que são dados que ele pode ler, como o conteúdo de uma issue ou de um arquivo de documentação. A terceira são prompts, que são instruções prontas que o servidor oferece para tarefas comuns. Na prática, você vai usar principalmente as ferramentas.
Por que isso importa? Sem MCP, se você quiser que o Claude verifique o esquema real do banco, ele precisa adivinhar a partir das migrações ou você precisa colar a saída de um comando. Com um servidor de banco de dados conectado, ele consulta o esquema sozinho, confere os dados e escreve código com base na realidade, não em suposições.
Adicionando servidores com o comando claude mcp
Servidores são gerenciados fora da sessão interativa, pelo subcomando claude mcp. Os quatro comandos que você mais vai usar são claude mcp add para adicionar, claude mcp list para listar, claude mcp get seguido do nome para ver detalhes, e claude mcp remove para retirar.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
Existem dois tipos principais de transporte. O transporte stdio executa um programa na sua máquina e conversa com ele pela entrada e saída padrão. É o caso típico de servidores instalados via npm ou Python. O transporte HTTP conecta a um serviço remoto por uma URL. É o caso de serviços hospedados, como o servidor oficial do GitHub. Você ainda pode encontrar o transporte SSE, mais antigo, mas o HTTP é o caminho recomendado hoje.
Veja um exemplo de servidor local para PostgreSQL. Repare no traço duplo, que separa as opções do Claude Code do comando que inicia o servidor:
claude mcp add --transport stdio banco -- npx -y @modelcontextprotocol/server-postgres "$DATABASE_URL"Repare que esse servidor de referência recebe a string de conexão como argumento, e não por uma variável chamada DATABASE_URL. Por isso lemos a variável de ambiente na hora de montar o comando, em vez de digitar a senha ali. Ele oferece acesso somente leitura e, mesmo assim, aponte-o para um banco de desenvolvimento.
E um exemplo de servidor remoto via HTTP:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/Escopos de configuração
Assim como o settings.json tem três níveis, os servidores MCP têm três escopos, escolhidos com a opção --scope. O escopo local é o padrão: o servidor vale apenas para você, apenas neste projeto, e fica gravado na configuração do usuário. O escopo project grava a definição em um arquivo chamado .mcp.json na raiz do projeto, que você versiona no Git para que todo o time receba os mesmos servidores. O escopo user torna o servidor disponível em todos os seus projetos, útil para algo como um servidor de documentação.
Uma regra prática: use project para servidores que todo o time precisa, como o banco de desenvolvimento e o GitHub, e nunca coloque senhas nesse arquivo. Referencie variáveis de ambiente com a sintaxe de cifrão e chaves, e cada pessoa define a sua no próprio ambiente. Ao abrir um projeto com .mcp.json pela primeira vez, o Claude Code pede sua aprovação antes de ativar os servidores, exatamente porque um servidor pode executar código na sua máquina.
Autenticação com serviços remotos
Serviços remotos costumam exigir login. Dentro da sessão, o comando de barra /mcp lista os servidores e, para os que usam OAuth, oferece a opção de autenticar. O navegador abre, você autoriza, e o token fica guardado. Para serviços que usam chave fixa, passe o cabeçalho na hora de adicionar, com a opção --header, novamente lendo a chave de uma variável de ambiente em vez de digitá-la no comando.
Casos de uso concretos
Consultar um banco de dados. Com o servidor PostgreSQL da API de tarefas conectado, você pode pedir: verifique no banco se existem tarefas com prazo anterior à data de criação e me mostre a consulta usada. O Claude executa a consulta, mostra o resultado e você valida antes de qualquer correção. Conecte sempre um banco de desenvolvimento ou um usuário somente leitura, jamais produção com permissão de escrita.
Ler issues e pull requests. No capítulo onze usamos o GitHub CLI. O servidor MCP do GitHub faz algo parecido, mas com ferramentas estruturadas que devolvem dados prontos para o modelo. Um pedido típico: leia a issue quarenta e dois, resuma o problema relatado e localize no código onde ele acontece, sem alterar nada.
Acessar documentação de bibliotecas. Um dos erros mais comuns da IA é inventar funções que não existem ou usar versões antigas de uma API. Servidores de documentação, como o Context7, entregam a documentação atual da versão que você usa. Basta pedir: consulte a documentação do Prisma na versão do projeto antes de escrever a migração.
Controlar um navegador. O servidor Playwright permite que o Claude abra páginas, clique, preencha formulários e tire capturas de tela. Isso transforma a verificação de interface em algo que ele faz sozinho: abra a aplicação em localhost, crie uma tarefa com prazo para amanhã e confirme que ela aparece na lista com a data correta.
Integrar ferramentas internas. Se sua empresa tem uma API de deploy, um catálogo de serviços ou um sistema de tickets, um servidor MCP interno expõe essas operações ao Claude. Aqui vale ainda mais o cuidado com escopo e permissões, que veremos a seguir.
Verificando ferramentas e controlando permissões
Depois de adicionar um servidor, inicie o Claude Code e digite /mcp. Você verá cada servidor com seu estado, conectado ou com falha, e poderá expandir a lista de ferramentas que ele oferece. Toda ferramenta MCP recebe um nome no formato mcp__servidor__ferramenta, com dois sublinhados entre as partes. Por exemplo, a consulta do banco aparece como mcp__banco__query.
Esse nome é o que você usa nas listas allow e deny do settings.json, do mesmo jeito que fez com Bash e Edit no capítulo seis. Você pode permitir uma ferramenta específica, escrevendo o nome completo, ou um servidor inteiro, escrevendo só mcp__ seguido do nome do servidor. Curingas com asterisco não funcionam para ferramentas MCP:
{ "permissions": { "allow": ["mcp__docs", "mcp__github__get_issue"], "deny": ["mcp__banco__execute"] } }Por padrão, cada ferramenta MCP pede aprovação como qualquer outra ação. Libere sem confirmação apenas as que são somente leitura e não têm efeito colateral, como ler documentação. Mantenha em deny qualquer ferramenta que escreve em sistemas reais.
Depurando um servidor que não conecta
Quando o /mcp mostra um servidor com falha, siga esta ordem. Primeiro, rode claude mcp get com o nome do servidor e confira se o comando e os argumentos estão corretos. Segundo, execute o mesmo comando diretamente no terminal, fora do Claude: se ele falhar ali, o problema é do servidor ou do ambiente, como uma variável não definida ou um pacote não instalado. Terceiro, inicie o Claude Code com a opção --debug para ver o log de conexão; em versões antigas essa opção se chamava --mcp-debug, hoje descontinuada. Quarto, se o servidor demora a iniciar, aumente o tempo limite com a variável de ambiente MCP_TIMEOUT em milissegundos. Para servidores remotos, confira proxy corporativo e se a autenticação ainda é válida, refazendo o login pelo /mcp.
Confie apenas em servidores conhecidos
Um servidor MCP stdio é um programa rodando com as suas permissões de usuário. Um servidor malicioso pode ler arquivos, enviar dados para fora ou devolver textos com injeção de prompt tentando manipular o Claude, o mesmo risco que vimos em conteúdo externo no capítulo seis. Por isso, instale apenas servidores oficiais dos fornecedores ou de repositórios que você leu e confia, fixe a versão em vez de usar sempre a mais recente, e trate os dados retornados por um servidor como informação, nunca como instrução. Se um resultado de consulta ou uma issue contiver algo como ignore as regras anteriores, isso é um alerta, não um comando.
Se quiser criar o seu próprio servidor
Programar um servidor MCP está fora do escopo deste livro, mas o caminho é curto. A Anthropic mantém SDKs oficiais em TypeScript e em Python. Com algumas dezenas de linhas você declara uma ferramenta, define os parâmetros com um esquema e escreve a função que executa a ação. Um bom exercício é pedir ao próprio Claude Code, com o servidor de documentação conectado, que gere um servidor mínimo que exponha uma operação interna da sua empresa como ferramenta.
Recapitulando
O Model Context Protocol conecta o Claude Code a sistemas fora do projeto por meio de servidores que oferecem ferramentas, recursos e prompts. Você adiciona servidores com claude mcp add, escolhendo entre transporte stdio para programas locais e HTTP para serviços remotos, e entre os escopos local, project e user. Casos de uso práticos incluem consultar bancos, ler issues e pull requests, obter documentação atualizada, controlar um navegador e integrar ferramentas internas. O comando /mcp mostra o estado e as ferramentas disponíveis, e as regras allow e deny controlam o que roda sem aprovação. Depure com claude mcp get, execução direta no terminal e --debug. E instale apenas servidores conhecidos, mantendo segredos em variáveis de ambiente e tratando dados externos como informação, não como ordem.
