Solución de problemas
Buscá tu síntoma, leé la causa y aplicá el arreglo. Cada entrada tiene su propio enlace, así otras páginas pueden apuntar directo a ella.
401 Unauthorized
Ves {"jsonrpc":"2.0","error":{"code":-32001,"message":"Unauthorized"}}, o tu cliente dice que el servidor "rejected the configured Authorization header (HTTP 401)".
Causa: /mcp necesita el token de Kernl. Falta el encabezado, o el token es incorrecto o está vencido (por ejemplo, fijaste un KERNEL_AUTH_TOKEN nuevo).
Arreglo: imprimí el token actual (mirá Primer arranque) y actualizá tu cliente. En Claude Code, quitá el servidor y agregalo de nuevo. Mirá Claude Code. Revisá el texto exacto del encabezado: Authorization: Bearer <token>.
Unexpected token '<'
Tu cliente dice Unexpected token '<', Unrecognized token '<' o "<!DOCTYPE" is not valid JSON.
Causa: el cliente esperaba JSON y recibió HTML. El < es el comienzo de <!DOCTYPE html>. Lo habitual es que el token falte o sea incorrecto: el cliente intentó iniciar sesión de otra manera y el dashboard respondió con su página web. Una URL equivocada es una causa probable del mismo resultado.
Arreglo: tratalo como un 401. Revisá el token, y revisá que la URL termine en /mcp y use el puerto 3086.
Session not found
Recibís 404 con {"jsonrpc":"2.0","error":{"code":-32000,"message":"Session not found"}}.
Causa: el mcp-session-id que mandaste es desconocido. Kernl puede haberlo eliminado después de 10 minutos de silencio (según el código fuente), o Kernl puede haberse reiniciado.
Arreglo: mandá initialize de nuevo y usá el nuevo id de sesión. Mirá Otros clientes. Las apps normales lo hacen solas. Si alguna no lo hace, reiniciala.
Missing mcp-session-id
Recibís 400 con Missing mcp-session-id header.
Causa: mandaste un pedido que necesita sesión, como GET /mcp, sin el encabezado mcp-session-id. Un tools/list sin el encabezado da Bad Request: Server not initialized.
Arreglo: llamá primero a initialize y mandá el mcp-session-id devuelto en cada pedido posterior. Mirá Conceptos básicos de MCP.
El puerto 3086 está en uso
Kernl no arranca, o el dashboard muestra otro programa.
Causa: otra cosa ya está escuchando en el puerto 3086.
Arreglo: encontrá ese programa y detenelo. En Windows podés mover Kernl en cambio (según el packaging, no lo corrimos nosotros): definí DASHBOARD_PORT=3088 en %APPDATA%\Kernl\.env y reiniciá. Acordate de usar el puerto nuevo en la URL de MCP.
No token yet
kernl token imprime kernl: no token yet — it is generated on the first boot. y termina con un error.
Causa: Kernl nunca arrancó, así que no generó un token.
Arreglo: iniciá Kernl una vez, esperá unos segundos y corré el comando de nuevo. En Linux:
systemctl --user start kernl
kernl token
La línea de systemctl es la que sugiere el propio kernl token; no la corrimos, porque nuestros contenedores de prueba no tienen systemd. Esto vale para los paquetes deb y rpm. Con el tarball no hay servicio: corré kernl directamente y, si ~/.local/bin no está en tu PATH, llamá a ~/.local/bin/kernl token.
En macOS abrí la app una vez. En Windows corré start.bat una vez. Con el tarball, corré kernl.
Accesible desde mi red
Otras computadoras de tu red pueden abrir tu dashboard.
Causa: por defecto los paquetes de Linux escuchan en todas las direcciones (0.0.0.0). Nadie puede iniciar sesión sin el token, pero la página se ve.
Arreglo: limitá Kernl a esta computadora. Agregá esta línea a ~/.config/kernl/.env y reiniciá Kernl:
KERNEL_DASHBOARD_BIND=127.0.0.1
Este ajuste sale del código de Kernl; no lo probamos. Si lo hacés, una dirección de la LAN tampoco va a funcionar en tu cliente MCP.
Aviso de "desarrollador no identificado" o de SmartScreen
macOS dice que no se puede abrir Kernl, o Windows dice que protegió tu PC.
Causa: los builds de macOS y Windows todavía no están firmados.
Arreglo en macOS: tocá Listo, abrí Ajustes del Sistema, Privacidad y seguridad, y tocá Abrir de todos modos. O corré:
xattr -dr com.apple.quarantine /Applications/Kernl.app
Arreglo en Windows: cuando diga "Windows protegió su PC", tocá Más información y después Ejecutar de todas formas.
Los pasos de macOS y Windows salen del packaging de Kernl; el equipo todavía no los probó en esos sistemas.
Claude Desktop típicamente muestra "Server disconnected"
Causa: una probable es Node 18 o anterior. El puente necesita Node 20.
Arreglo: corré node --version y actualizá si hace falta. Mirá Claude Desktop.
Neo4j unavailable en el log
El log dice Neo4j unavailable — graph features will be disabled.
Causa: una instalación por paquete no trae base de datos Neo4j.
Arreglo: no hace falta ninguno. Es inofensivo. Solo quedan apagadas las funciones de grafo.