# 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:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   # 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**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **Atualize para a versão mais recente**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   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](/docs/mcp/claude-desktop)
- [Configuração do Claude Code](/docs/mcp/claude-code)
- [Erros da API](/docs/api/errors)