🔌 MCP Nao Conecta
🎯 Diagnostico de Conexao
O problema mais comum com MCPs: voce adiciona mas o status mostra 'disconnected'. As causas mais frequentes sao: comando do server errado, pacote npm nao encontrado, ou dependencia faltando (Node.js, Chrome).
-
•
Passo 1:
claude mcp list- confirme o status -
•
Passo 2:
claude mcp remove nome- remova o MCP problematico -
•
Passo 3: Teste o comando isolado:
npx -y @anthropic/mcp-xxx --help - • Passo 4: Re-adicione com o comando correto e verifique com /status
📊 Causas Mais Comuns
- Nome do pacote errado: confira no npm registry
- Node.js nao instalado: verifique com 'node --version'
- npx nao disponivel: 'npm install -g npx'
- Sem internet: npx precisa baixar o pacote na primeira vez
💡 Dica Pratica
O fix que resolve 80% dos problemas de conexao: remove + re-add. Se o MCP estava funcionando antes e parou, um simples 'claude mcp remove nome' seguido de 'claude mcp add nome -- comando' reseta tudo. E o equivalente de 'desligar e ligar de novo' para MCPs.
✓ O que FAZER
- ✓ Testar o comando do server isoladamente primeiro
- ✓ Usar remove + re-add como primeiro fix
- ✓ Verificar dependencias (Node.js, Chrome)
✗ O que NAO fazer
- ✗ Assumir que o problema e do MCP sem diagnosticar
- ✗ Tentar usar tools de MCP disconnected
- ✗ Ignorar erros de instalacao
🚫 Permission Denied
🎯 Erros de Permissao
O MCP conecta com sucesso mas retorna 'permission denied' ou 'access denied' ao usar tools. Isso geralmente indica que o token/credencial nao tem os escopos necessarios ou o caminho nao esta autorizado.
- • GitHub: Verifique escopos do PAT (precisa de repo, read:org)
- • Filesystem: Verifique se o caminho requisitado esta nos caminhos autorizados
- • Database: Verifique permissoes do usuario SQL (GRANT SELECT)
- • Sheets: Verifique se a planilha foi compartilhada com o service account
📊 Diagnostico Por MCP
- GitHub: github.com → Settings → Developer settings → verifique escopos do token
- Filesystem: claude mcp remove + re-add com caminhos corretos
- Database: conecte manualmente e teste permissoes do usuario
- Sheets: abra a planilha e verifique compartilhamento
💡 Dica Pratica
Para cada MCP, crie um teste de permissao simples: GitHub → 'liste 1 issue do repo'. Filesystem → 'liste arquivos em ~/projetos'. Database → 'SELECT 1'. Sheets → 'leia celula A1 da planilha'. Se o teste passa, a permissao esta OK. Se falha, o problema e de credencial.
✓ O que FAZER
- ✓ Criar testes de permissao simples para cada MCP
- ✓ Verificar escopos de tokens e permissoes
- ✓ Resolver permissao ANTES de tentar usar o MCP
✗ O que NAO fazer
- ✗ Assumir que conexao = permissao (sao coisas diferentes)
- ✗ Usar tokens com permissoes excessivas para 'resolver'
- ✗ Ignorar erros de permissao e tentar de novo
📈 Token Usage Alto
🎯 Consumo Excessivo de Contexto
O /cost mostra consumo muito acima do esperado. As causas mais comuns sao: muitos MCPs conectados simultaneamente, queries que retornam grandes volumes de dados, ou screenshots frequentes do Browser MCP.
-
•
Diagnostico 1:
claude mcp list- quantos MCPs estao ativos? - • Diagnostico 2: Some os overheads: Filesystem(500) + GitHub(2000) + Browser(5000) = 7500/msg
- • Fix 1: Remova MCPs nao essenciais para a tarefa atual
- • Fix 2: Use LIMIT em queries e evite screenshots desnecessarios
📊 Tabela de Diagnostico Rapido
- 1 MCP ativo mas token alto → dados retornados grandes (use LIMIT)
- 3+ MCPs ativos → overhead acumulado (remova nao essenciais)
- Browser ativo + screenshots → cada screenshot custa 5k-15k tokens
- Tudo normal mas token alto → sessao longa, rode /compact
💡 Dica Pratica
Workflow de diagnostico em 30 segundos: 1) /cost - veja o numero. 2) claude mcp list - conte MCPs ativos. 3) Calcule overhead teorico. 4) Se overhead > 30% do contexto usado, remova MCPs. 5) Se overhead e baixo mas token alto, e a sessao que esta longa - rode /compact.
✓ O que FAZER
- ✓ Diagnosticar causa antes de agir
- ✓ Remover MCPs nao essenciais como primeiro fix
- ✓ Usar /compact para sessoes longas
✗ O que NAO fazer
- ✗ Culpar o modelo quando token esta alto
- ✗ Ignorar o overhead cumulativo de MCPs
- ✗ Continuar usando sem investigar a causa
🐌 Respostas Lentas
🎯 Diagnosticando Latencia
Respostas demoram muito mais que o normal. Pode ser causado por: MCP server lento, contexto muito cheio, ou servidor externo com timeout.
-
•
Diagnostico 1:
/cost- contexto esta cheio? (>80% = lento) - • Diagnostico 2: Teste sem MCPs - ainda lento? E do modelo/rede
- • Diagnostico 3: Teste cada MCP individual - qual e lento?
- • Fix: /compact se contexto alto, reinicie MCP se e do server, aguarde se e da rede
📊 Causas Por Prioridade
- Mais provavel: contexto cheio (>80%) → Fix: /compact
- Segundo: MCP server travado → Fix: remove + re-add
- Terceiro: rede lenta → Fix: aguarde ou troque de rede
- Quarto: servidor externo (GitHub API, DB) lento → Fix: tente novamente depois
💡 Dica Pratica
Teste rapido para isolar a causa: desconecte todos os MCPs e envie uma mensagem simples. Se responde rapido, o problema e um dos MCPs. Reconecte um por um ate encontrar o lento. Se continua lento sem MCPs, rode /cost - provavelmente e contexto cheio.
✓ O que FAZER
- ✓ Isolar a causa: contexto vs MCP vs rede
- ✓ Testar sem MCPs para baseline
- ✓ Usar /compact como primeiro fix para contexto cheio
✗ O que NAO fazer
- ✗ Assumir que e 'o Claude que esta lento'
- ✗ Enviar mais mensagens enquanto esta lento
- ✗ Ignorar e esperar resolver sozinho
❌ Server Not Found
🎯 MCP Server Nao Encontrado
Erro ao adicionar MCP: 'server not found', 'command not found' ou 'module not found'. Isso indica que o pacote npm nao existe, o nome esta errado, ou o ambiente Node.js nao esta configurado.
-
•
Fix 1: Verifique nome do pacote:
npm info @anthropic/mcp-xxx -
•
Fix 2: Confirme Node.js:
node --version(precisa v18+) -
•
Fix 3: Confirme npx:
npx --version -
•
Fix 4: Teste isolado:
npx -y @anthropic/mcp-xxx --help
📊 Causas Comuns
- Nome do pacote mudou (ecossistema MCP evolui rapido)
- Node.js desatualizado (precisa v18+ para a maioria dos MCPs)
- npx nao instalado ou nao no PATH
- Firewall/proxy bloqueando download do pacote npm
💡 Dica Pratica
Se o pacote nao e encontrado, pode ser que o nome mudou. Busque no npm: npx -y npm search @anthropic/mcp para ver todos os pacotes MCP oficiais da Anthropic. Para MCPs de terceiros, verifique a documentacao oficial do MCP no GitHub.
✓ O que FAZER
- ✓ Verificar nome exato do pacote no npm
- ✓ Manter Node.js atualizado (v18+)
- ✓ Testar npx isolado antes de adicionar ao Claude
✗ O que NAO fazer
- ✗ Inventar nomes de pacotes
- ✗ Usar Node.js < v18
- ✗ Ignorar erros de npx
📜 Checklist do Operador
🎯 Troubleshooting Universal
Quando algo nao funciona com MCPs, siga este checklist em ordem. Ele resolve 95% dos problemas sem necessidade de pesquisa externa.
-
•
1.
/status- MCP aparece? Esta connected? -
•
2.
claude mcp list- Config esta correta? -
•
3.
claude mcp remove nome + re-add- Reseta conexao -
•
4.
/doctor- Diagnostico geral do Claude Code - • 5. Reinicie a sessao do Claude Code completamente
- • 6. Verifique dependencias (Node.js, Chrome, credenciais)
📊 As Tres Regras de Ouro
- Regra #1: Sempre comece pelo /status - 50% dos problemas sao vistos aqui
- Regra #2: Remove + re-add resolve 80% dos problemas remanescentes
- Regra #3: Se nada funcionar, reinicie a sessao completamente
💡 Dica Pratica
Salve este checklist como alias no shell: alias mcp-fix='echo "1. /status" && echo "2. claude mcp list" && echo "3. claude mcp remove NAME + re-add" && echo "4. /doctor" && echo "5. Reinicie sessao" && echo "6. Check deps"'. Quando algo quebrar, rode 'mcp-fix' para lembrar os passos na ordem certa.
✓ O que FAZER
- ✓ Seguir o checklist NA ORDEM apresentada
- ✓ Parar quando o problema for resolvido (nao execute todos se o 1o resolve)
- ✓ Documentar problemas recorrentes e suas solucoes
✗ O que NAO fazer
- ✗ Pular direto para solucoes avancadas
- ✗ Tentar fixes aleatorios sem diagnosticar
- ✗ Reinstalar Claude Code como primeiro recurso
📋 Resumo do Modulo
Proximo:
Trilha 6 - Conectando o Claude (MCPs)