Tutorial de MCP no Claude Code: adicione servidores do jeito certo
Conecte Context7, Playwright ou qualquer servidor MCP ao Claude Code — transportes, escopos, o arquivo .mcp.json, chaves de API e o painel /mcp, em um único passeio ilustrado.
A versão curta
- Um comando instala qualquer servidor: claude mcp add name -- npx -y @scope/package para servidores locais, ou claude mcp add --transport http name url para os remotos.
- Existem três transportes: stdio executa um comando na sua máquina, SSE é a forma remota antiga e streamable HTTP é a opção remota moderna.
- Três escopos decidem quem ganha o servidor: local (só você), project (compartilhado via .mcp.json) e user (todos os seus projetos).
- Rode /mcp dentro de uma sessão para ver status e ferramentas; a primeira chamada de ferramenta pede permissão, e você pode permitir uma vez ou sempre.
Claude Code Tutorial #7 - MCP Servers
Canal: The Net Ninja14:16
Claude Code MCP: How to Add MCP Servers (Complete Guide)
Canal: Leon van Zyl17:58
Model Context Protocol (MCP) — official Claude Code docs
Documentação: code.claude.com/docs
Os screenshots vêm do capítulo do The Net Ninja — uma gravação de tela cheia e limpa. A anatomia dos comandos, escopos e correções de Windows segue o walkthrough mais completo do Leon van Zyl mais a documentação oficial.
Os frames pertencem aos respectivos criadores e são creditados aqui com deep links para os momentos exatos; o texto é nosso.
Do zero a dois servidores MCP funcionando
Parte 1 · O que os servidores MCP destravam
- 1
O que o MCP dá ao Claude Code
O Claude Code vem com ferramentas nativas para arquivos e shell, mas tudo fora da sua base de código está fora do alcance. MCP — o Model Context Protocol — é o caminho padrão da Anthropic para plugar ferramentas extras: um servidor expõe capacidades, e o Claude Code chama essas capacidades como qualquer ferramenta nativa.
O slide do curso que define o MCP em uma linha.Ver em 0:52 - 2
Escolha servidores de acordo com a tarefa
Cada servidor traz suas próprias ferramentas. O servidor do Supabase lista tabelas, faz deploy de edge functions e roda SQL; o Playwright controla um navegador de verdade; o Context7 serve documentação atualizada de frameworks. Comece pelo que eliminar sua tarefa repetitiva mais chata.
O exemplo do Supabase: três ferramentas, um serviço externo.Ver em 1:24 - 3
Ache o comando de instalação no README do servidor
Os autores de servidores publicam um comando pronto para o Claude Code no README — Context7 e Playwright fazem isso. Diretórios como o PulseMCP facilitam ver o que existe antes de se comprometer com qualquer coisa.
O README do Playwright MCP documenta recursos e requisitos.Ver em 2:02 - 4
Entenda os três tipos de transporte
A documentação oficial divide as instalações em locais e remotas. Um servidor stdio executa um comando na sua máquina — é o padrão. Servidores SSE e HTTP são endpoints remotos com os quais você conecta; SSE é o formato antigo e o streamable HTTP é seu substituto. A sintaxe do claude mcp add muda um pouco em cada caso.
A página da documentação comparando stdio local com SSE e HTTP remotos.Ver em 3:02
Parte 2 · Adicione seu primeiro servidor
- 5
Adicione o Context7 com escopo project
No terminal: claude mcp add context7 --scope project -- npx -y @upstash/context7-mcp. O nome você escolhe, tudo depois do traço duplo é o comando a executar, e o --scope project grava o servidor na configuração compartilhada do projeto em vez da pessoal.
O comando exato para adicionar o servidor de documentação Context7.Ver em 5:22 - 6
Leia o .mcp.json gerado
Servidores com escopo project caem num arquivo .mcp.json na raiz do repositório, sob a chave mcpServers. Cada entrada registra o tipo — stdio aqui — mais o comando e os argumentos: o mesmo formato que o Cursor ou o Claude Desktop usam.
Dentro do .mcp.json: type, command e args do servidor stdio.Ver em 6:42 - 7
Usuários de Windows: cuidado com o prefixo cmd /c
No Windows nativo sem WSL, os comandos stdio precisam de cmd /c antes do npx para o shell fechar limpo depois que o servidor termina. A documentação avisa isso num box de alerta, e o vídeo mostra o ajuste exato.
O box de alerta oficial para servidores stdio no Windows.Ver em 3:24 - 8
Confirme que o arquivo entrou no repositório
Depois de um add com escopo project, o .mcp.json aparece no explorador como arquivo novo sem versionamento, pronto para o commit e para que os colegas recebam os mesmos servidores. Servidores com escopo local nunca tocam esse arquivo.
Um .mcp.json novo na raiz do projeto, sem versionamento e pronto para commit.Ver em 8:32 - 9
Prefere remoto? Use o transporte HTTP
Quando um build stdio se comporta mal, o endpoint remoto é a saída rápida: claude mcp add --transport http context7 --scope project https://mcp.context7.com/mcp. Sem processo local e sem npm — o Claude Code fala direto com a URL.
A variante HTTP do comando de adicionar apontando para o endpoint do Context7.Ver em 8:36 - 10
Confira a conexão no /mcp
Inicie o Claude Code e rode /mcp. Cada servidor mostra status e lista de ferramentas. Uma falha normalmente se resolve com a reconexão embutida; se não, a seção de solução de problemas abaixo cobre as causas comuns.
O painel /mcp mostrando o context7 conectado com suas duas ferramentas.Ver em 9:22
Parte 3 · Use os servidores no trabalho real
- 11
Chame o servidor num prompt real
Peça algo que as ferramentas nativas não fazem e nomeie o servidor: «confere a documentação mais recente do Tailwind contra meu arquivo CSS global — usa o context7». Anexar o arquivo com uma menção @ ancora a resposta no seu código.
O prompt que pede documentação atual do Tailwind via context7.Ver em 9:38 - 12
Aprove a chamada de ferramenta
Na primeira vez que uma ferramenta de servidor roda, o Claude Code pede permissão. Aprove uma vez, ou escolha permitir sempre nos servidores de confiança para que as chamadas seguintes passem sem perguntar.
O cartão de permissão da ferramenta resolve-library-id do Context7.Ver em 10:00 - 13
Leia a resposta com lastro
A ferramenta devolve a documentação relevante — aqui a orientação de variáveis de tema do Tailwind v4 — com o custo em tokens exibido, e o Claude Code aplica no seu arquivo. Esse é todo o ponto: respostas da documentação vigente em vez de chute dos dados de treino.
A resposta do get-library-docs confirmando a configuração do tema.Ver em 10:15 - 14
Fixe o hábito no CLAUDE.md
Digite o símbolo de hash para adicionar uma memória de projeto, por exemplo: «use o Context7 para documentação atualizada ao implementar bibliotecas ou frameworks novos». A linha cai no CLAUDE.md e toda sessão futura herda.
Uma memória de uma linha no CLAUDE.md que torna o Context7 o padrão.Ver em 10:42 - 15
Adicione um segundo servidor: Playwright
Repita o padrão para automação de navegador: claude mcp add playwright --scope project -- cmd /c npx @playwright/mcp@latest — e tire a parte do cmd /c no macOS ou Linux. Um repositório, vários servidores, um arquivo de configuração.
Adicionando o servidor Playwright MCP com escopo project.Ver em 11:22 - 16
Veja-o pilotar o navegador
Peça ao Claude Code para abrir uma página e resumi-la — o Playwright navega, clica e lê, e depois reporta. Com a documentação do Context7 e o navegador do Playwright, a maioria das tarefas externas fica a um prompt de distância.
O Playwright MCP navegando até um site para resumir.Ver em 12:42
Variáveis de ambiente, headers e chaves de API
Servidores remotos e APIs com autenticação precisam de credenciais. O Claude Code as recebe como variáveis de ambiente em servidores stdio e como headers nos remotos — sem editar arquivo de configuração na mão.
- 1Servidores stdio: claude mcp add myserver -e API_KEY=your-key -e ZONE=your-zone -- npx -y @some/mcp-server — repita a flag -e para cada variável, logo depois do nome do servidor.
- 2Servidores HTTP remotos: claude mcp add --transport http myserver https://example.com/mcp --header "Authorization: Bearer your-key" — o header vai junto de cada chamada de ferramenta.
- 3Revisão de escopos: local deixa o servidor só para você neste projeto, project compartilha via .mcp.json, e user instala em todos os seus projetos. Define com -s ou --scope ao adicionar.
- 4Remover um servidor: claude mcp remove name — no escopo project, faça commit da mudança no .mcp.json para que o servidor suma também para os colegas.
Valores passados com -e ficam em texto puro dentro do arquivo de configuração. Prefira chaves de permissão estreita onde a API permitir, e nunca faça commit de credenciais reais num .mcp.json de escopo project.
Quando o /mcp mostra failed
Quase toda falha de MCP no Claude Code volta a poucas causas. Percorra esta lista antes de apagar e readicionar qualquer coisa.
- 1Unknown option -y no Windows: alguns terminais travam nessa flag do npm. Rode o comando de adicionar no PowerShell ou no Prompt de Comando, ou tire o -y, adicione o servidor e depois devolva o -y ao array args do .mcp.json na mão.
- 2stdio falha no Windows nativo: prefixe o comando com cmd /c — por exemplo cmd /c npx -y @some/package@latest. Sem WSL é obrigatório, e a tag @latest evita builds velhos em cache.
- 3Status em failed: abra o /mcp e reconecte — falhas passageiras normalmente resolvem na segunda tentativa. Se não, o painel mostra o local do log do servidor para o erro real.
- 4Servidor não aparece no outro projeto: é o escopo funcionando como deveria. Servidores com escopo project vivem no .mcp.json daquele repositório; troque para o escopo user para instalar na máquina inteira.
- 5Servidor conecta mas nunca é usado: nomeie no prompt — «usa o context7 para checar a documentação» — ou adicione uma memória no CLAUDE.md, porque sem indicação os modelos agarram as ferramentas nativas de sempre.
Quando nada resolve: claude mcp remove name, reinicie o terminal e adicione o servidor de novo pelo transporte que você sabe que funciona — a variante HTTP remota é a mais previsível.