Solución de problemas de MCP

Problemas comunes y soluciones al integrar Synapse MCP con su cliente LLM.

Lista rápida de diagnóstico

1. ✅ ¿Node.js 18+ instalado? (node --version)
2. ✅ ¿El Mind Key empieza por mk_? (no JWT eyJ...)
3. ✅ ¿La API de Synapse es alcanzable? (curl https://synapse.schaefer.zone/health)
4. ✅ ¿El Mind Key funciona? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
5. ✅ ¿El archivo de configuración es JSON válido? (sin comas finales, sin comentarios)
6. ✅ ¿Reinició el cliente tras el cambio de configuración?
7. ✅ ¿El servidor MCP arranca manualmente? (npx -y synapse-mcp-api@latest)

Problema: no aparecen herramientas en el cliente

Síntomas

• Claude Desktop / Cursor / Continue muestra 0 herramientas
• No aparece el icono 🔌 ni la entrada "synapse" en la lista de servidores MCP

Soluciones

1. Reinicie el cliente completamente — Cmd+Q en macOS (no solo cerrar la ventana)
2. Compruebe la ubicación del archivo de configuración:
   • 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 el JSON — pegue la configuración en https://jsonlint.com
4. Revise los logs del cliente para errores MCP:
   • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor: View → Output → MCP
5. Ejecute el servidor MCP manualmente para ver errores de arranque:

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

Problema: error "Mind Key invalid"

Síntomas

• Las herramientas aparecen pero las llamadas fallan con "401 Unauthorized"
• Error: "Mind Key fehlt oder ungültig"

Soluciones

1. Verifique el formato del Mind Key — empieza por mk_, ~40 caracteres
2. Pruebe directamente:

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

3. Compruebe que la variable de entorno está establecida — para transporte stdio, la variable de entorno debe estar en la configuración del servidor MCP, no en su shell
4. Obtenga un Mind Key nuevo:

   # 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 no encontrado

Síntomas

• Error: "npx: command not found"
• El servidor MCP no arranca

Soluciones

1. Instale Node.js 18+:
   • macOS: brew install node o descargue desde https://nodejs.org
   • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows: descargue desde https://nodejs.org
2. Reinicie el terminal tras la instalación
3. Verifique: node --version && npx --version

Problema: SYNAPSE_URL inalcanzable

Síntomas

• El servidor MCP arranca pero las llamadas a herramientas agotan el tiempo
• Error: "fetch failed" o "ECONNREFUSED"

Soluciones

1. Pruebe la conectividad:

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

2. Compruebe el firewall corporativo — puede bloquear HTTPS saliente
3. Pruebe una URL alternativa:
   • Producción: https://synapse.schaefer.zone
   • Servidor MCP: https://synapse-mcp.schaefer.zone
4. Para autoalojamiento: asegúrese de que su instancia de Synapse está corriendo y accesible

Problema: el servidor MCP se cuelga

Síntomas

• El servidor MCP sale inmediatamente tras arrancar
• Los logs del cliente muestran "MCP server disconnected"

Soluciones

1. Ejecútelo manualmente para ver el error:

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

2. Compruebe conflictos de puerto — el servidor MCP usa el puerto 13100 por defecto
3. Limpie la caché de npx:

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

4. Actualice a la última versión:

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

Problema: las llamadas a herramientas devuelven 429

Síntomas

• Error: "Rate limit exceeded"

Soluciones

Esto no debería ocurrir con MCP (usa auth por cabecera, sin límite de frecuencia). Si ocurre:

1. Compruebe si está usando ?key= en algún sitio — cambie a auth por cabecera
2. Verifique SYNAPSE_URL — asegúrese de que apunta a la instancia correcta
3. Contacte con soporte si el problema persiste

Problema: las herramientas aparecen pero no funcionan

Síntomas

• Herramientas listadas en el cliente
• Llamar a una herramienta devuelve un error o ningún resultado

Soluciones

1. Compruebe el nombre de la herramienta — debe ser exacto (p. ej. memory_recall, no memory.recall)
2. Verifique los argumentos — compruebe el esquema de entrada de la herramienta
3. Pruebe vía API directa:

   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. Compruebe la salud de Synapse:

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

Obtener ayuda

Si ninguna de las soluciones anteriores resuelve su problema:

1. Compruebe los issues existentes: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
2. Abra un issue nuevo con:
   • Versión del servidor MCP (npx -y synapse-mcp-api@latest --version)
   • Nombre y versión del cliente
   • Sistema operativo
   • Extractos de logs relevantes
   • Pasos para reproducir

Próximos pasos

• Configuración de Claude Desktop
• Configuración de Claude Code
• Errores de la API