Kernl

MCP basics

MCP is a standard way for an AI app to use outside tools. Kernl runs an MCP server, so apps like Claude Code can call Kernl's tools. Every client needs the same two things: a URL and a token.

The URL

Kernl's MCP endpoint is:

http://localhost:3086/mcp

It is the same address with Docker. There nginx forwards /mcp to the kernel, so you still use port 3086.

The token

/mcp rejects any request without the Kernl token. Send it as a bearer token in the Authorization header:

Authorization: Bearer <token>

Print your token with the command for your system. See First run or the table in Where things are.

Without the header, or with a wrong token, Kernl answers 401 Unauthorized. Many clients show this as a confusing error. See 401 Unauthorized and Unexpected token '<'.

Sessions

You only need this section if you write your own client. Apps like Claude Code do it for you.

  1. Send an initialize request. The reply carries an mcp-session-id header.
  2. Send that header with every later request.
  3. A session that sits idle for 10 minutes can be removed. The next call with its id then fails with 404 Session not found, and the client has to send initialize again.

Expired sessions are cleaned up only when another client connects, so a quiet session can last longer than 10 minutes. Kernl also keeps at most 256 sessions open at once. Beyond that, a new initialize gets a 503 "Server busy" reply.

Replies are Server-Sent Events: lines that start with event: message and data:. Your client must accept both application/json and text/event-stream.

Pick your client