# Solución de problemas de MCP
SUMMARY: Resuelva problemas comunes de integración de MCP — servidor que no arranca, herramientas que no aparecen, errores 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/

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? ()
2. ✅ ¿El Mind Key empieza por ? (no JWT )
3. ✅ ¿La API de Synapse es alcanzable? ()
4. ✅ ¿El Mind Key funciona? ()
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? ()
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: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. Valide el JSON — pegue la configuración en <https://jsonlint.com>
4. Revise los logs del cliente para errores MCP:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. Ejecute el servidor MCP manualmente para ver errores de arranque:
   [CODE BLOCK]
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 , 40 caracteres
2. Pruebe directamente:
   [CODE BLOCK]
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:
   [CODE BLOCK]
Problema: npx no encontrado
Síntomas
- Error: "npx: command not found"
- El servidor MCP no arranca
Soluciones
1. Instale Node.js 18+:
   - macOS:  o descargue desde <https://nodejs.org>
   - Linux: 
   - Windows: descargue desde <https://nodejs.org>
2. Reinicie el terminal tras la instalación
3. Verifique: 
Problema: SYNAPSEURL 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:
   [CODE BLOCK]
2. Compruebe el firewall corporativo — puede bloquear HTTPS saliente
3. Pruebe una URL alternativa:
   - Producción: 
   - Servidor MCP: 
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:
   [CODE BLOCK]
2. Compruebe conflictos de puerto — el servidor MCP usa el puerto 13100 por defecto
3. Limpie la caché de npx:
   [CODE BLOCK]
4. Actualice a la última versión:
   [CODE BLOCK]
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  en algún sitio — cambie a auth por cabecera
2. Verifique  — 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. , no )
2. Verifique los argumentos — compruebe el esquema de entrada de la herramienta
3. Pruebe vía API directa:
   [CODE BLOCK]
4. Compruebe la salud de Synapse:
   [CODE BLOCK]
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 ()
   - 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