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? (node --version)
2. ✅ Mind Key começa com mk_? (não JWT eyJ...)
3. ✅ API do Synapse alcançável? (curl https://synapse.schaefer.zone/health)
4. ✅ Mind Key funciona? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
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? (npx -y synapse-mcp-api@latest)

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: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Cursor: ~/.cursor/config.json
   • Continue: ~/.continue/config.json
3. Valide o JSON — cole a config em https://jsonlint.com
4. Confira os logs do cliente para erros de MCP:
   • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor: View → Output → MCP
5. Rode o servidor MCP manualmente para ver erros de inicialização:

   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest

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 mk_, ~40 caracteres
2. Teste diretamente:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

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:

   # Login to get JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Create new mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

Problema: npx não encontrado

Sintomas

• Erro: "npx: command not found"
• Servidor MCP falha ao iniciar

Soluções

1. Instale Node.js 18+:
   • macOS: brew install node ou baixe de https://nodejs.org
   • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows: baixe de https://nodejs.org
2. Reinicie o terminal após instalar
3. Verifique: node --version && npx --version

Problema: SYNAPSE_URL inalcançável

Sintomas

• Servidor MCP inicia, mas chamadas de ferramenta dão timeout
• Erro: "fetch failed" ou "ECONNREFUSED"

Soluções

1. Teste conectividade:

   curl https://synapse.schaefer.zone/health

2. Confira firewall corporativo — pode bloquear HTTPS de saída
3. Tente URL alternativa:
   • Produção: https://synapse.schaefer.zone
   • Servidor MCP: https://synapse-mcp.schaefer.zone
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:

   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest

2. Confira conflitos de porta — servidor MCP usa a porta 13100 por padrão
3. Limpe o cache do npx:

   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx

4. Atualize para a versão mais recente:

   npx -y synapse-mcp-api@latest --version

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 ?key= em algum lugar — mude para auth por cabeçalho
2. Verifique SYNAPSE_URL — 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.: memory_recall, não memory.recall)
2. Verifique os argumentos — confira o schema de entrada da ferramenta
3. Teste via API direta:

   curl -X POST https://synapse.schaefer.zone/memory \
     -H "Authorization: Bearer mk_..." \
     -H "Content-Type: application/json" \
     -d '{"category":"fact","key":"test","content":"hello"}'

4. Confira a saúde do Synapse:

   curl https://synapse.schaefer.zone/health

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 (npx -y synapse-mcp-api@latest --version)
   • 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