# MCP Troubleshooting
SUMMARY: Resolva problemas comuns de integração MCP — servidor não inicia, ferramentas não aparecem, erros de auth.

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

MCP Troubleshooting
Problemas comuns e soluções ao integrar o MCP do Synapse com seu cliente LLM.
Checklist rápido de diagnóstico
1. ✅ Node.js 18+ instalado? ()
2. ✅ Mind Key começa com ? (não JWT )
3. ✅ API do Synapse alcançável? ()
4. ✅ Mind Key funciona? ()
5. ✅ Arquivo de config é JSON válido? (sem vírgulas no final, sem comentários)
6. ✅ Cliente reiniciado após mudança de config?
7. ✅ Servidor MCP inicia manualmente? ()
Problema: nenhuma ferramenta aparece no cliente
Sintomas
- Claude Desktop / Cursor / Continue mostra 0 ferramentas
- Sem ícone 🔌 ou entrada "synapse" na lista de servidores MCP
Soluções
1. Reinicie o cliente totalmente — Cmd+Q no macOS (não apenas feche a janela)
2. Confira o local do arquivo de config:
   - Claude Desktop macOS: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. Valide o JSON — cole a config em <https://jsonlint.com>
4. Confira os logs do cliente para erros de MCP:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. Rode o servidor MCP manualmente para ver erros de inicialização:
   [CODE BLOCK]
Problema: erro "Mind Key invalid"
Sintomas
- Ferramentas aparecem, mas chamadas falham com "401 Unauthorized"
- Erro: "Mind Key fehlt oder ungültig"
Soluções
1. Verifique o formato da Mind Key — começa com , 40 caracteres
2. Teste diretamente:
   [CODE BLOCK]
3. Confira se a env var está definida — para transporte stdio, a env var deve estar na config do servidor MCP, não no seu shell
4. Obtenha uma nova Mind Key:
   [CODE BLOCK]
Problema: npx não encontrado
Sintomas
- Erro: "npx: command not found"
- Servidor MCP falha ao iniciar
Soluções
1. Instale Node.js 18+:
   - macOS:  ou baixe de <https://nodejs.org>
   - Linux: 
   - Windows: baixe de <https://nodejs.org>
2. Reinicie o terminal após instalar
3. Verifique: 
Problema: SYNAPSEURL inalcançável
Sintomas
- Servidor MCP inicia, mas chamadas de ferramenta dão timeout
- Erro: "fetch failed" ou "ECONNREFUSED"
Soluções
1. Teste conectividade:
   [CODE BLOCK]
2. Confira firewall corporativo — pode bloquear HTTPS de saída
3. Tente URL alternativa:
   - Produção: 
   - Servidor MCP: 
4. Para auto-hospedagem: garanta que sua instância do Synapse esteja rodando e acessível
Problema: servidor MCP trava
Sintomas
- Servidor MCP sai imediatamente após iniciar
- Logs do cliente mostram "MCP server disconnected"
Soluções
1. Rode manualmente para ver o erro:
   [CODE BLOCK]
2. Confira conflitos de porta — servidor MCP usa a porta 13100 por padrão
3. Limpe o cache do npx:
   [CODE BLOCK]
4. Atualize para a versão mais recente:
   [CODE BLOCK]
Problema: chamadas de ferramenta retornam 429
Sintomas
- Erro: "Rate limit exceeded"
Soluções
Isso não deveria acontecer com MCP (usa auth por cabeçalho, sem limite de
taxa). Se acontecer:
1. Verifique se você está usando  em algum lugar — mude para auth por cabeçalho
2. Verifique  — garanta que aponta para a instância correta
3. Contate o suporte se o problema persistir
Problema: ferramentas aparecem, mas não funcionam
Sintomas
- Ferramentas listadas no cliente
- Chamar uma ferramenta retorna erro ou nenhum resultado
Soluções
1. Confira o nome da ferramenta — deve ser exato (ex.: , não )
2. Verifique os argumentos — confira o schema de entrada da ferramenta
3. Teste via API direta:
   [CODE BLOCK]
4. Confira a saúde do Synapse:
   [CODE BLOCK]
Obtendo ajuda
Se nada acima resolver seu problema:
1. Confira issues existentes: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. Abra uma nova issue com:
   - Versão do servidor MCP ()
   - Nome e versão do cliente
   - Sistema operacional
   - Trechos de log relevantes
   - Passos para reproduzir
Próximos passos
- Configuração do Claude Desktop
- Configuração do Claude Code
- Erros da API