runlot docs

runlot mcp runs a Model Context Protocol server on stdio, so an AI coding agent can deploy, read logs, query the database, and search these docs through your own login.

runlot mcp turns the CLI into a Model Context Protocol server. An agent that connects to it can do what you can do from the terminal — list projects, deploy, read logs, run a query, look something up in these docs — without you pasting output back and forth.

It speaks JSON-RPC over stdin and stdout, which is how MCP clients launch a local server. There is nothing to host and no extra credential: the server uses the session runlot login already stored.

Setup

runlot mcp install prints the snippet for your client. It does not write the file — these configs usually hold other servers, so the edit stays in your hands.

runlot mcp install claude-code
runlot mcp install cursor
runlot mcp install claude-desktop

The configuration is the same shape everywhere.

{
  "mcpServers": {
    "runlot": {
      "command": "runlot",
      "args": ["mcp"]
    }
  }
}

Client	File
Claude Code	`claude mcp add runlot -- runlot mcp`, or `.mcp.json` in the project
Cursor	`~/.cursor/mcp.json`, or `.cursor/mcp.json` in the project
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)

Signing in

The server uses the login session for the control plane it is pointed at, exactly as the other commands do. If it starts without one, it prints the login command and exits with code 2 — the client shows that as a failed server rather than an empty tool list.

runlot login

Where the client has an environment of its own — a container, or a desktop app that does not see your shell — set a token in the client's env instead:

{
  "mcpServers": {
    "runlot": {
      "command": "runlot",
      "args": ["mcp"],
      "env": { "RUNLOT_TOKEN": "rl_…" }
    }
  }
}

The tools

Most of the tools are the REST API, one tool per operation, generated from the API specification when the CLI is built. That is why the list does not go stale: an endpoint that ships is a tool the next release publishes, with the spec's own summary as its description.

Four more are hand-written, because they are not single HTTP calls:

Tool	What it does
`runlot_deploy`	Builds and deploys a directory — the same path as `runlot deploy <dir>`, including creating the project, granting what `runlot.json` declares, and applying `migrations/`
`runlot_logs_tail`	The last N lines of a project's worker logs. It does not follow
`runlot_pg_execute`	SQL against the project database. Read-only unless the call passes `allow_write`
`runlot_docs_search`	Searches these docs (`llms-full.txt`) and returns the matching passages, cached for a day

The generated tools take orgSlug and projectName as arguments. The four above also read runlot.json from a directory, so an agent working inside a project does not have to ask you for names.

runlot_pg_execute runs your SQL inside a read-only transaction that is then rolled back. A SELECT is always safe; anything that writes has to pass allow_write, and an agent should ask you first.

Keeping it safe

Destructive tools ask for consent in the call itself. Deleting an org, a project or a database, restoring, rolling back, buying or renewing a domain, and removing a DNS record all carry a description beginning with DESTRUCTIVE: and refuse to run unless the call includes "confirm": true. Without it the tool returns an error naming the argument, and no request reaches the server.

--read-only publishes the reads and nothing else.

runlot mcp --read-only

The write tools are not hidden behind a refusal — they are not in the tool list at all, so an agent never spends a turn discovering it is not allowed. It is the setting to use for an agent running unattended.

Options

runlot mcp takes the same options as the rest of the CLI. --api points it at another control plane, --org and --project supply a default target for the tools that read runlot.json, and --ca-dir is the local CA that runlot_pg_execute verifies the database with.

While the server is running, stdout belongs to the protocol. Do not pipe anything else into it, and do not run runlot mcp in a shell where you also expect to read output.

MCP server