# 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:
   ```bash
   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**:
   ```bash
   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**:
   ```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 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**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **Actualice a la última versión**:
   ```bash
   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**:
   ```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. **Compruebe la salud de Synapse**:
   ```bash
   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](/docs/mcp/claude-desktop)
- [Configuración de Claude Code](/docs/mcp/claude-code)
- [Errores de la API](/docs/api/errors)