kater serve

Starts the Kater MCP server, which gives an AI agent Kater's tools.

You seldom run it by hand: your agent’s MCP client starts it from its settings. Platform admins run the hosted server with --mode remote.

Examples

# Serve the local copy in this folder to one agent over stdio, as kater agent sets it up
kater serve --kater-root .
# Serve several local agents at one address, behind the token in KATER_MCP_TOKEN
kater serve --transport http --port 8765
# Serve without keeping compile results on disk
kater serve --no-cache
# Run the hosted server, behind PropelAuth sign-in
kater serve --mode remote

Options

Option	Description
`--mode <mode>`	`local` serves your local copy on this machine. It has no sign-in of its own, so anyone who can start the process can use it. `remote` runs the hosted server, behind PropelAuth sign-in, and passes each tool call to the Kater API. The default is `local`.
`--transport <transport>`	For local mode. `stdio` serves the one agent that started the server. `http` serves several agents on `127.0.0.1`, and admits only requests that carry the token in `KATER_MCP_TOKEN`. The default is `stdio`.
`--port <n>`	The port for `--transport http`. `0` takes a free port. The default is `0`.
`--no-cache`	Keeps no compile results on disk. Without it, the server shares them with the editor’s server and the CLI commands on this machine.
`--cache-dir <folder>`	The folder for the compile results that the server shares. Left out, it is `~/.cache/kater-query-server`.

It also takes the global options --json, --kater-root, --scope and --help.

Who runs it

Your agent, over stdio. kater agent claude and kater agent codex write MCP settings for your local copy. They run kater serve --kater-root .. The agent then starts the server. Its log goes to stderr, since stdout carries the protocol.
Several local agents, over HTTP. Set KATER_MCP_TOKEN first: the server does not start without it. It prints {"serving": "http://127.0.0.1:<port>/mcp"} once its port is open. It stops when the process that started it exits.
Platform admins, for the hosted server. --mode remote serves Streamable HTTP at /mcp. It reads its address and sign-in settings from environment variables, such as KATER_MCP_PORT, which is 8000 unless set. --transport, --port and the cache options apply only to local mode.

Agents and the Files terminal cannot run kater serve. See MCP server and tools.

Your open pages

When you signed in with kater login, a local server can see your open Kater pages. Without a sign-in, its tools say that they cannot. Run kater login, then start kater serve again.

Settings

Each option can also come from an environment variable, such as KATER_SERVE_MODE. A flag wins over it. See Configuration.

Editor intelligence, such as completions and diagnostics, comes from a separate server, kater-lsp. See VS Code extension.