{"title":"Solución de problemas de MCP","slug":"troubleshooting","category":"mcp","summary":"Resuelva problemas comunes de integración de MCP — servidor que no arranca, herramientas que no aparecen, errores de auth.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":648,"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":"es","translated":true,"requested_lang":"es","content_markdown":"\n# Solución de problemas de MCP\n\nProblemas comunes y soluciones al integrar Synapse MCP con su cliente LLM.\n\n## Lista rápida de diagnóstico\n\n1. ✅ ¿Node.js 18+ instalado? (`node --version`)\n2. ✅ ¿El Mind Key empieza por `mk_`? (no JWT `eyJ...`)\n3. ✅ ¿La API de Synapse es alcanzable? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ ¿El Mind Key funciona? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ ¿El archivo de configuración es JSON válido? (sin comas finales, sin comentarios)\n6. ✅ ¿Reinició el cliente tras el cambio de configuración?\n7. ✅ ¿El servidor MCP arranca manualmente? (`npx -y synapse-mcp-api@latest`)\n\n## Problema: no aparecen herramientas en el cliente\n\n### Síntomas\n\n- Claude Desktop / Cursor / Continue muestra 0 herramientas\n- No aparece el icono 🔌 ni la entrada \"synapse\" en la lista de servidores MCP\n\n### Soluciones\n\n1. **Reinicie el cliente completamente** — Cmd+Q en macOS (no solo cerrar la ventana)\n2. **Compruebe la ubicación del archivo de configuración**:\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 el JSON** — pegue la configuración en \n4. **Revise los logs del cliente** para errores MCP:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **Ejecute el servidor MCP manualmente** para ver errores de arranque:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Problema: error \"Mind Key invalid\"\n\n### Síntomas\n\n- Las herramientas aparecen pero las llamadas fallan con \"401 Unauthorized\"\n- Error: \"Mind Key fehlt oder ungültig\"\n\n### Soluciones\n\n1. **Verifique el formato del Mind Key** — empieza por `mk_`, ~40 caracteres\n2. **Pruebe directamente**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **Compruebe que la variable de entorno está establecida** — para transporte\n stdio, la variable de entorno debe estar en la configuración del servidor\n MCP, no en su shell\n4. **Obtenga un Mind Key nuevo**:\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 no encontrado\n\n### Síntomas\n\n- Error: \"npx: command not found\"\n- El servidor MCP no arranca\n\n### Soluciones\n\n1. **Instale Node.js 18+**:\n - macOS: `brew install node` o descargue desde \n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: descargue desde \n2. **Reinicie el terminal** tras la instalación\n3. **Verifique**: `node --version && npx --version`\n\n## Problema: SYNAPSE_URL inalcanzable\n\n### Síntomas\n\n- El servidor MCP arranca pero las llamadas a herramientas agotan el tiempo\n- Error: \"fetch failed\" o \"ECONNREFUSED\"\n\n### Soluciones\n\n1. **Pruebe la conectividad**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Compruebe el firewall corporativo** — puede bloquear HTTPS saliente\n3. **Pruebe una URL alternativa**:\n - Producción: `https://synapse.schaefer.zone`\n - Servidor MCP: `https://synapse-mcp.schaefer.zone`\n4. **Para autoalojamiento**: asegúrese de que su instancia de Synapse está corriendo y accesible\n\n## Problema: el servidor MCP se cuelga\n\n### Síntomas\n\n- El servidor MCP sale inmediatamente tras arrancar\n- Los logs del cliente muestran \"MCP server disconnected\"\n\n### Soluciones\n\n1. **Ejecútelo manualmente para ver el error**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Compruebe conflictos de puerto** — el servidor MCP usa el puerto 13100 por defecto\n3. **Limpie la caché de npx**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **Actualice a la última versión**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Problema: las llamadas a herramientas devuelven 429\n\n### Síntomas\n\n- Error: \"Rate limit exceeded\"\n\n### Soluciones\n\nEsto no debería ocurrir con MCP (usa auth por cabecera, sin límite de\nfrecuencia). Si ocurre:\n\n1. **Compruebe si está usando `?key=` en algún sitio** — cambie a auth por cabecera\n2. **Verifique `SYNAPSE_URL`** — asegúrese de que apunta a la instancia correcta\n3. **Contacte con soporte** si el problema persiste\n\n## Problema: las herramientas aparecen pero no funcionan\n\n### Síntomas\n\n- Herramientas listadas en el cliente\n- Llamar a una herramienta devuelve un error o ningún resultado\n\n### Soluciones\n\n1. **Compruebe el nombre de la herramienta** — debe ser exacto (p. ej. `memory_recall`, no `memory.recall`)\n2. **Verifique los argumentos** — compruebe el esquema de entrada de la herramienta\n3. **Pruebe vía API directa**:\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. **Compruebe la salud de Synapse**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Obtener ayuda\n\nSi ninguna de las soluciones anteriores resuelve su problema:\n\n1. **Compruebe los issues existentes**: \n2. **Abra un issue nuevo** con:\n - Versión del servidor MCP (`npx -y synapse-mcp-api@latest --version`)\n - Nombre y versión del cliente\n - Sistema operativo\n - Extractos de logs relevantes\n - Pasos para reproducir\n\n## Próximos pasos\n\n- [Configuración de Claude Desktop](/docs/mcp/claude-desktop)\n- [Configuración de Claude Code](/docs/mcp/claude-code)\n- [Errores de la API](/docs/api/errors)\n","content_html":"

Solución de problemas de MCP

\n

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

\n

Lista rápida de diagnóstico

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

Problema: no aparecen herramientas en el cliente

\n

Síntomas

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

Soluciones

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

Problema: error "Mind Key invalid"

\n

Síntomas

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

Soluciones

\n
    \n
  1. Verifique el formato del Mind Key — empieza por mk_, ~40 caracteres
    2. \n
  2. Pruebe directamente:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  3. Compruebe que la variable de entorno está establecida — para transporte\nstdio, la variable de entorno debe estar en la configuración del servidor\nMCP, no en su shell
    4. \n
  4. Obtenga un Mind Key nuevo:
    # 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 no encontrado

\n

Síntomas

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

Soluciones

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

Problema: SYNAPSE_URL inalcanzable

\n

Síntomas

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

Soluciones

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

Problema: el servidor MCP se cuelga

\n

Síntomas

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

Soluciones

\n
    \n
  1. Ejecútelo manualmente para ver el error:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. Compruebe conflictos de puerto — el servidor MCP usa el puerto 13100 por defecto
    3. \n
  3. Limpie la caché de npx:
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. Actualice a la última versión:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

Problema: las llamadas a herramientas devuelven 429

\n

Síntomas

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

Soluciones

\n

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

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

Problema: las herramientas aparecen pero no funcionan

\n

Síntomas

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

Soluciones

\n
    \n
  1. Compruebe el nombre de la herramienta — debe ser exacto (p. ej. memory_recall, no memory.recall)
    2. \n
  2. Verifique los argumentos — compruebe el esquema de entrada de la herramienta
    3. \n
  3. Pruebe vía API directa:
    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. Compruebe la salud de Synapse:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

Obtener ayuda

\n

Si ninguna de las soluciones anteriores resuelve su problema:

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

Próximos pasos

\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"]}