Se você ja entendeu o que e MCP e quer colocar isso para trabalhar de verdade, o próximo passo e simples: conectar um servidor MCP no Claude Code, testar uma chamada pequena e transformar a configuração em um padrão repetivel.
Resposta rápida: no Claude Code, o caminho mais comum e usar claude mcp add para adicionar um servidor remoto HTTP, um servidor local via stdio ou uma configuração compartilhada de projeto. Depois você confere com /mcp, autentica com claude mcp login quando o servidor usa OAuth e guarda segredos em variaveis de ambiente, não direto no arquivo do projeto.
Este guia foi escrito em 17/07/2026, com base na documentacao atual do Claude Code e do Model Context Protocol. O objetivo aqui não e listar todos os servidores possiveis, mas te deixar com um roteiro seguro para instalar, validar e corrigir erros sem ficar copiando comando aleatorio de README.
Antes de conectar: escolha o tipo certo de MCP
Nem todo servidor MCP deve ser conectado do mesmo jeito. A diferenca principal esta em onde o servidor roda e quem deve ter acesso a configuração.
| Tipo de servidor | Como costuma rodar | Quando usar |
|---|---|---|
| Remoto HTTP | Uma URL HTTPS exposta pelo provedor | SaaS, APIs, conectores oficiais, servidores com OAuth |
| Local stdio | Um processo local iniciado pelo Claude Code | Ferramentas locais, scripts internos, acesso a arquivos, prototipos |
Projeto .mcp.json |
Configuração versionavel no repositorio | Time trabalhando no mesmo projeto, padrão reproduzivel |
Usuário ~/.claude.json |
Configuração da sua maquina | Servidores pessoais que não devem ir para o repo |
Para um projeto como o ViniEnsina, o melhor padrão e separar:
- MCPs de trabalho local e sensiveis ficam no escopo de usuário.
- MCPs necessarios para qualquer pessoa reproduzir o projeto podem ir em
.mcp.json. - Tokens, chaves e URLs privadas sempre entram via variavel de ambiente.
Pre-requisitos
Antes de rodar qualquer comando, confira quatro coisas:
- Claude Code instalado e logado.
- Você sabe se o servidor e remoto HTTP, local stdio ou WebSocket.
- Você confia no servidor MCP e entende quais ferramentas ele expoe.
- Você tem os tokens ou permissao OAuth, se o conector exigir autenticacao.
A própria documentacao da Anthropic alerta que servidores MCP externos podem trazer conteúdo não confiavel para dentro da conversa. Isso importa porque uma ferramenta com acesso a arquivos, automacoes ou banco de dados não e so "mais um plugin"; ela vira uma ponte real entre o modelo e o seu ambiente.
Método 1: conectar um servidor MCP remoto HTTP
Para servidores remotos, o padrão e usar claude mcp add com transporte HTTP:
“bash claude mcp add --transport http nome-do-servidor https://exemplo.com/mcp “
Em um caso real, o comando fica parecido com:
“bash claude mcp add --transport http paypal https://mcp.paypal.com/mcp “
Use esse formato quando o provedor entrega uma URL de MCP. E o tipo de setup mais comum para conectores SaaS, porque o servidor não precisa rodar na sua maquina.
Depois de adicionar, abra o painel MCP dentro do Claude Code:
“text /mcp “
O que você quer ver:
- O servidor aparece na lista.
- O status não mostra erro de transporte.
- As ferramentas aparecem com nomes compreensiveis.
- O servidor pede aprovacao/autenticacao quando necessário.
Método 2: autenticar servidor MCP com OAuth
Alguns servidores remotos exigem login OAuth. Nesse caso, depois de adicionar o servidor, rode:
“bash claude mcp login nome-do-servidor “
Se você estiver em ambiente sem navegador, a CLI atual também documenta a opção de fluxo sem browser:
“bash claude mcp login nome-do-servidor --no-browser “
Use OAuth quando o provedor suportar. Evite colar token permanente em arquivo de configuração se existe fluxo oficial de login.
Método 3: conectar um MCP local via stdio
Servidores locais normalmente rodam como um processo iniciado pelo Claude Code. O padrão e separar os argumentos do comando com --:
“bash claude mcp add meu-servidor -- node caminho/do/servidor.js “
Ou, para um servidor Python:
“bash claude mcp add meu-servidor -- python caminho/do/server.py “
No Windows, prefira caminhos absolutos quando o servidor não estiver dentro do repositorio atual. Isso reduz erro bobo de diretoria de trabalho.
Exemplo prático:
“bash claude mcp add ferramentas-vini -- C:\Users\Vinicius\Gemini\.venv\Scripts\python.exe C:\Users\Vinicius\Gemini\tools\mcp\server.py “
Esse tipo de servidor e bom para:
- Ler arquivos locais.
- Rodar scripts internos.
- Criar ferramentas especificas do projeto.
- Integrar automacoes que ainda não merecem virar API publica.
Método 4: compartilhar MCP no projeto com .mcp.json
Quando a configuração precisa acompanhar o projeto, use escopo de projeto:
“bash claude mcp add --transport http nome-do-servidor --scope project https://exemplo.com/mcp “
O Claude Code guarda essa configuração em um arquivo .mcp.json na raiz do projeto. Esse arquivo pode ir para o Git quando ele não contem segredo direto.
Um exemplo simplificado:
“json { "mcpServers": { "analytics": { "type": "http", "url": "https://exemplo.com/mcp" } } } “
Para times, esse e o formato mais limpo: todo mundo sabe quais servidores o projeto espera, mas cada pessoa ainda autentica do seu jeito.
Variaveis de ambiente: o jeito certo de lidar com segredo
Se um servidor precisa de token, use variavel de ambiente. A documentacao do Claude Code aceita expansão no .mcp.json, como ${VAR} e ${VAR:-default}.
Exemplo:
“json { "mcpServers": { "minha-api": { "type": "http", "url": "${MCP_API_URL}", "headers": { "Authorization": "Bearer ${MCP_API_TOKEN}" } } } } “
No Windows PowerShell, você pode definir temporariamente:
“powershell $env:MCP_API_TOKEN="seu-token" “
Para uso permanente, configure pelo gerenciador de variaveis do sistema ou por um arquivo local que não entre no Git.
Timeouts: quando o servidor demora para responder
Alguns MCPs fazem chamadas pesadas: navegador, banco, busca, arquivos grandes. Se o servidor inicia devagar, use MCP_TIMEOUT.
“powershell $env:MCP_TIMEOUT="60000" “
Para timeout por servidor em .mcp.json, a documentacao também permite configurar timeout em milissegundos.
Exemplo:
“json { "mcpServers": { "relatorios": { "type": "http", "url": "https://exemplo.com/mcp", "timeout": 600000 } } } “
Não aumente timeout como primeira resposta a todo erro. Antes, confirme se a URL esta certa, se o servidor esta online e se a autenticacao passou.
Checklist de seguranca antes de aprovar um MCP
Antes de clicar aprovando tudo, faca uma revisao rápida:
| Pergunta | Por que importa |
|---|---|
| O servidor vem de fonte confiavel? | MCP pode executar ferramentas reais no seu ambiente |
| Quais ferramentas ele expoe? | Um servidor de leitura e diferente de um servidor que escreve/deleta |
| Ele acessa arquivos locais? | Escopo de diretorio precisa ser mínimo |
| Ele acessa APIs pagas? | Uma chamada errada pode gerar custo |
| Ele recebe conteúdo externo? | Conteúdo externo pode tentar induzir o modelo a agir errado |
| Segredos estao fora do Git? | Token em repo privado ainda e risco operacional |
Para servidores de producao, trate MCP como trataria uma integração de API: menor privilegio possível, logs, revisao periodica e remocao do que não e usado.
Troubleshooting: erros comuns
O servidor aparece, mas não conecta
Confira:
- URL com
https://. - Transporte correto: HTTP, stdio ou WebSocket.
- VPN/proxy/firewall.
- Token ou OAuth valido.
- Nome do servidor sem espaco estranho.
O OAuth não abre navegador
Use:
“bash claude mcp login nome-do-servidor --no-browser “
Depois siga o link/código exibido pela CLI.
O servidor local funciona no terminal, mas falha no Claude Code
Quase sempre e caminho ou ambiente. Use caminho absoluto para o runtime e para o script. No Windows, isso evita confusao entre python, Python Store alias, venv e diretorio atual.
O .mcp.json pede aprovacao toda hora
Servidores de projeto passam por fluxo de confianca. Se você precisar resetar escolhas do projeto, a documentacao cita:
“bash claude mcp reset-project-choices “
Use com cuidado: isso refaz a decisão de confianca do projeto.
O comando trava em tarefa longa
Suba timeout apenas para servidores que realmente precisam:
- Browser automation.
- Raspagem de páginas pesadas.
- Relatórios grandes.
- Consultas lentas em banco.
Se tudo precisa de timeout gigante, o problema provavelmente e desenho do servidor, não configuração.
Exemplo de setup recomendado para um projeto local
Para um projeto privado/local como um blog operacional, eu usaria este desenho:
| Necessidade | Escopo recomendado |
|---|---|
| Ferramentas pessoais do Codex/Claude | Usuário |
| Servidores que todo colaborador precisa conhecer | Projeto |
| Tokens de WordPress, GA4, Search Console, n8n | Variavel de ambiente |
| Scripts experimentais | Local stdio, sem commit até estabilizar |
| Automacoes de producao | HTTP com logs e credenciais separadas |
O melhor sinal de maturidade não e ter 30 MCPs conectados. E ter poucos MCPs que reduzem trabalho repetitivo sem aumentar o risco de publicar, apagar, duplicar ou vazar coisa importante.
Depois de conectar: como testar sem quebrar nada
Faca um teste pequeno:
- Abra
/mcpe confirme as ferramentas. - Peca uma ação de leitura, não escrita.
- Confira se o retorno vem no formato esperado.
- So depois teste uma ação com escrita.
- Para escrita, comece com dry-run, arquivo temporario ou ambiente de teste.
Exemplo de prompt seguro:
“text Use o servidor MCP X apenas para listar os recursos disponiveis. Nao altere, delete, publique ou envie nada. “
Depois:
“text Agora use o servidor MCP X para simular a criacao do recurso Y em modo dry-run e me mostre o payload antes de executar. “
Esse habito economiza muito retrabalho.
Perguntas frequentes
Preciso de MCP para usar o Claude Code?
Não. O Claude Code funciona sem MCP. MCP entra quando você quer conectar o modelo a ferramentas, dados, APIs ou sistemas externos de forma mais padronizada.
Posso commitar .mcp.json?
Pode, se ele não tiver segredo direto. O ideal e commitar apenas a configuração reproduzivel e deixar tokens em variaveis de ambiente ou OAuth local.
Qual e melhor: MCP remoto ou local?
Remoto e melhor para SaaS e conectores oficiais. Local e melhor para scripts internos, arquivos da maquina e prototipos. Em projeto serio, os dois convivem.
O que fazer se um servidor MCP pedir permissao demais?
Não aprove no impulso. Revise as ferramentas expostas, reduza escopo, procure alternativa ou rode em ambiente isolado. MCP bom precisa resolver uma dor clara.
Claude Desktop e Claude Code usam MCP do mesmo jeito?
Eles usam a mesma ideia de protocolo, mas o fluxo de configuração pode mudar. Este tutorial e focado no Claude Code e nos comandos claude mcp.
Fontes e metodologia
Este artigo foi produzido a partir da documentacao oficial consultada em 17/07/2026 e do fluxo prático usado no projeto ViniEnsina.