Kernl

Claude Desktop

Claude Desktop only starts local programs, so it cannot talk to Kernl's URL directly. A small bridge called mcp-remote sits in between. It needs Node.js.

Do not use the old bun snippet

Older notes show a config that runs bun run bin/mcp-server.ts. Do not use it. It needs a source checkout of Kernl, and a packaged install has no such file: in the source the script is services/kernel/bin/mcp-server.ts, not bin/mcp-server.ts at the root. It also boots a separate kernel instead of connecting to the one you installed.

Check your Node version

You need Node 20 or newer. Node 18 fails with ReferenceError: File is not defined, and Claude Desktop typically shows "Server disconnected".

node --version

Edit the config file

macOS and Windows steps come from mcp-remote's documentation; the Kernl team has not run them on those systems yet.

Open claude_desktop_config.json. It lives here:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add Kernl under mcpServers:

{
  "mcpServers": {
    "kernl": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3086/mcp",
        "--header",
        "Authorization:${KERNL_AUTH}"
      ],
      "env": {
        "KERNL_AUTH": "Bearer <token>"
      }
    }
  }
}

Replace <token> with the output of your token command, see First run. Keep Bearer and the space after it.

Write Authorization: with no space after the colon. The space goes inside the env value. This keeps the token out of the process list and works around how Claude Desktop passes arguments on Windows.

Restart Claude Desktop after you save.

Use a LAN address

mcp-remote accepts plain http:// only for localhost. If you point it at another machine, such as http://192.168.1.20:3086/mcp, add --allow-http before --header:

"args": ["-y", "mcp-remote", "http://192.168.1.20:3086/mcp", "--allow-http", "--header", "Authorization:${KERNL_AUTH}"]

Without it you get Non-HTTPS URLs are only allowed for localhost or when --allow-http flag is provided.

If it fails

A wrong token shows as Unexpected token '<', because the bridge gets the dashboard's HTML page instead of JSON. See Unexpected token '<' and 401 Unauthorized.