{"title":"MCP Troubleshooting","slug":"troubleshooting","category":"mcp","summary":"Resolva problemas comuns de integração MCP — servidor não inicia, ferramentas não aparecem, erros de auth.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":607,"read_minutes":3,"llm_context":"Common issues:\n1. Node.js < 18 → upgrade to 18+\n2. Mind Key invalid → check format (mk_...), get fresh via POST /minds\n3. npx not found → install Node.js\n4. Tools not appearing → restart client, check config JSON validity\n5. SYNAPSE_URL unreachable → curl /health to verify\n6. MCP server crashes → check logs, run npx manually to see error\nDebug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr\nLogs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/\n","lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# MCP Troubleshooting\n\nProblemas comuns e soluções ao integrar o MCP do Synapse com seu cliente LLM.\n\n## Checklist rápido de diagnóstico\n\n1. ✅ Node.js 18+ instalado? (`node --version`)\n2. ✅ Mind Key começa com `mk_`? (não JWT `eyJ...`)\n3. ✅ API do Synapse alcançável? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ Mind Key funciona? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ Arquivo de config é JSON válido? (sem vírgulas no final, sem comentários)\n6. ✅ Cliente reiniciado após mudança de config?\n7. ✅ Servidor MCP inicia manualmente? (`npx -y synapse-mcp-api@latest`)\n\n## Problema: nenhuma ferramenta aparece no cliente\n\n### Sintomas\n\n- Claude Desktop / Cursor / Continue mostra 0 ferramentas\n- Sem ícone 🔌 ou entrada \"synapse\" na lista de servidores MCP\n\n### Soluções\n\n1. **Reinicie o cliente totalmente** — Cmd+Q no macOS (não apenas feche a janela)\n2. **Confira o local do arquivo de config**:\n - Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - Claude Desktop Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n - Cursor: `~/.cursor/config.json`\n - Continue: `~/.continue/config.json`\n3. **Valide o JSON** — cole a config em \n4. **Confira os logs do cliente** para erros de MCP:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **Rode o servidor MCP manualmente** para ver erros de inicialização:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Problema: erro \"Mind Key invalid\"\n\n### Sintomas\n\n- Ferramentas aparecem, mas chamadas falham com \"401 Unauthorized\"\n- Erro: \"Mind Key fehlt oder ungültig\"\n\n### Soluções\n\n1. **Verifique o formato da Mind Key** — começa com `mk_`, ~40 caracteres\n2. **Teste diretamente**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **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\n4. **Obtenha uma nova Mind Key**:\n ```bash\n # Login to get JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # Create new mind\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## Problema: npx não encontrado\n\n### Sintomas\n\n- Erro: \"npx: command not found\"\n- Servidor MCP falha ao iniciar\n\n### Soluções\n\n1. **Instale Node.js 18+**:\n - macOS: `brew install node` ou baixe de \n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: baixe de \n2. **Reinicie o terminal** após instalar\n3. **Verifique**: `node --version && npx --version`\n\n## Problema: SYNAPSE_URL inalcançável\n\n### Sintomas\n\n- Servidor MCP inicia, mas chamadas de ferramenta dão timeout\n- Erro: \"fetch failed\" ou \"ECONNREFUSED\"\n\n### Soluções\n\n1. **Teste conectividade**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Confira firewall corporativo** — pode bloquear HTTPS de saída\n3. **Tente URL alternativa**:\n - Produção: `https://synapse.schaefer.zone`\n - Servidor MCP: `https://synapse-mcp.schaefer.zone`\n4. **Para auto-hospedagem**: garanta que sua instância do Synapse esteja rodando e acessível\n\n## Problema: servidor MCP trava\n\n### Sintomas\n\n- Servidor MCP sai imediatamente após iniciar\n- Logs do cliente mostram \"MCP server disconnected\"\n\n### Soluções\n\n1. **Rode manualmente para ver o erro**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Confira conflitos de porta** — servidor MCP usa a porta 13100 por padrão\n3. **Limpe o cache do npx**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **Atualize para a versão mais recente**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Problema: chamadas de ferramenta retornam 429\n\n### Sintomas\n\n- Erro: \"Rate limit exceeded\"\n\n### Soluções\n\nIsso não deveria acontecer com MCP (usa auth por cabeçalho, sem limite de\ntaxa). Se acontecer:\n\n1. **Verifique se você está usando `?key=` em algum lugar** — mude para auth por cabeçalho\n2. **Verifique `SYNAPSE_URL`** — garanta que aponta para a instância correta\n3. **Contate o suporte** se o problema persistir\n\n## Problema: ferramentas aparecem, mas não funcionam\n\n### Sintomas\n\n- Ferramentas listadas no cliente\n- Chamar uma ferramenta retorna erro ou nenhum resultado\n\n### Soluções\n\n1. **Confira o nome da ferramenta** — deve ser exato (ex.: `memory_recall`, não `memory.recall`)\n2. **Verifique os argumentos** — confira o schema de entrada da ferramenta\n3. **Teste via API direta**:\n ```bash\n curl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer mk_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"category\":\"fact\",\"key\":\"test\",\"content\":\"hello\"}'\n ```\n4. **Confira a saúde do Synapse**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Obtendo ajuda\n\nSe nada acima resolver seu problema:\n\n1. **Confira issues existentes**: \n2. **Abra uma nova issue** com:\n - Versão do servidor MCP (`npx -y synapse-mcp-api@latest --version`)\n - Nome e versão do cliente\n - Sistema operacional\n - Trechos de log relevantes\n - Passos para reproduzir\n\n## Próximos passos\n\n- [Configuração do Claude Desktop](/docs/mcp/claude-desktop)\n- [Configuração do Claude Code](/docs/mcp/claude-code)\n- [Erros da API](/docs/api/errors)\n","content_html":"

MCP Troubleshooting

\n

Problemas comuns e soluções ao integrar o MCP do Synapse com seu cliente LLM.

\n

Checklist rápido de diagnóstico

\n
    \n
  1. ✅ Node.js 18+ instalado? (node --version)
    2. \n
  2. ✅ Mind Key começa com mk_? (não JWT eyJ...)
    3. \n
  3. ✅ API do Synapse alcançável? (curl https://synapse.schaefer.zone/health)
    4. \n
  4. ✅ Mind Key funciona? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
    5. \n
  5. ✅ Arquivo de config é JSON válido? (sem vírgulas no final, sem comentários)
    6. \n
  6. ✅ Cliente reiniciado após mudança de config?
    7. \n
  7. ✅ Servidor MCP inicia manualmente? (npx -y synapse-mcp-api@latest)
    8. \n
\n

Problema: nenhuma ferramenta aparece no cliente

\n

Sintomas

\n
    \n
  • Claude Desktop / Cursor / Continue mostra 0 ferramentas
    • \n
  • Sem ícone 🔌 ou entrada "synapse" na lista de servidores MCP
    • \n
\n

Soluções

\n
    \n
  1. Reinicie o cliente totalmente — Cmd+Q no macOS (não apenas feche a janela)
    2. \n
  2. Confira o local do arquivo de config:
      \n
    • Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
      • \n
    • Claude Desktop Windows: %APPDATA%\\Claude\\claude_desktop_config.json
      • \n
    • Cursor: ~/.cursor/config.json
      • \n
    • Continue: ~/.continue/config.json
      • \n
    \n
    3. \n
  3. Valide o JSON — cole a config em https://jsonlint.com
    4. \n
  4. Confira os logs do cliente para erros de MCP:
      \n
    • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
      • \n
    • Cursor: View → Output → MCP
      • \n
    \n
    5. \n
  5. Rode o servidor MCP manualmente para ver erros de inicialização:
    SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
    6. \n
\n

Problema: erro "Mind Key invalid"

\n

Sintomas

\n
    \n
  • Ferramentas aparecem, mas chamadas falham com "401 Unauthorized"
    • \n
  • Erro: "Mind Key fehlt oder ungültig"
    • \n
\n

Soluções

\n
    \n
  1. Verifique o formato da Mind Key — começa com mk_, ~40 caracteres
    2. \n
  2. Teste diretamente:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  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. \n
  4. Obtenha uma nova Mind Key:
    # Login to get JWT\ncurl -X POST .../login -d '{"email":"...","password":"..."}'\n# Create new mind\ncurl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
    5. \n
\n

Problema: npx não encontrado

\n

Sintomas

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

Soluções

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

Problema: SYNAPSE_URL inalcançável

\n

Sintomas

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

Soluções

\n
    \n
  1. Teste conectividade:
    curl https://synapse.schaefer.zone/health
    2. \n
  2. Confira firewall corporativo — pode bloquear HTTPS de saída
    3. \n
  3. Tente URL alternativa:
      \n
    • Produção: https://synapse.schaefer.zone
      • \n
    • Servidor MCP: https://synapse-mcp.schaefer.zone
      • \n
    \n
    4. \n
  4. Para auto-hospedagem: garanta que sua instância do Synapse esteja rodando e acessível
    5. \n
\n

Problema: servidor MCP trava

\n

Sintomas

\n
    \n
  • Servidor MCP sai imediatamente após iniciar
    • \n
  • Logs do cliente mostram "MCP server disconnected"
    • \n
\n

Soluções

\n
    \n
  1. Rode manualmente para ver o erro:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. Confira conflitos de porta — servidor MCP usa a porta 13100 por padrão
    3. \n
  3. Limpe o cache do npx:
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. Atualize para a versão mais recente:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

Problema: chamadas de ferramenta retornam 429

\n

Sintomas

\n
    \n
  • Erro: "Rate limit exceeded"
    • \n
\n

Soluções

\n

Isso não deveria acontecer com MCP (usa auth por cabeçalho, sem limite de\ntaxa). Se acontecer:

\n
    \n
  1. Verifique se você está usando ?key= em algum lugar — mude para auth por cabeçalho
    2. \n
  2. Verifique SYNAPSE_URL — garanta que aponta para a instância correta
    3. \n
  3. Contate o suporte se o problema persistir
    4. \n
\n

Problema: ferramentas aparecem, mas não funcionam

\n

Sintomas

\n
    \n
  • Ferramentas listadas no cliente
    • \n
  • Chamar uma ferramenta retorna erro ou nenhum resultado
    • \n
\n

Soluções

\n
    \n
  1. Confira o nome da ferramenta — deve ser exato (ex.: memory_recall, não memory.recall)
    2. \n
  2. Verifique os argumentos — confira o schema de entrada da ferramenta
    3. \n
  3. Teste via API direta:
    curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer mk_..." \\\n  -H "Content-Type: application/json" \\\n  -d '{"category":"fact","key":"test","content":"hello"}'
    4. \n
  4. Confira a saúde do Synapse:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

Obtendo ajuda

\n

Se nada acima resolver seu problema:

\n
    \n
  1. Confira issues existentes: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
    2. \n
  2. Abra uma nova issue com:
      \n
    • Versão do servidor MCP (npx -y synapse-mcp-api@latest --version)
      • \n
    • Nome e versão do cliente
      • \n
    • Sistema operacional
      • \n
    • Trechos de log relevantes
      • \n
    • Passos para reproduzir
      • \n
    \n
    3. \n
\n

Próximos passos

\n\n","urls":{"html":"/docs/mcp/troubleshooting","text":"/docs/mcp/troubleshooting?format=text","json":"/docs/mcp/troubleshooting?format=json","llm":"/docs/mcp/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}