MCP

KamalCloud speaks the Model Context Protocol at POST /mcp. An MCP client – Claude, Cursor, anything that speaks the protocol – connects and gets one tool per action a person could take in the browser.

This is not a separate surface. Every controller action declares itself as a tool, and a call runs as a real request with the caller’s own credentials. The validations, the background jobs and the permission checks are the application’s, not a second implementation that drifts from it.

What a client sees

The tool list is built from the caller’s role. An action behind admin is offered to admins only, so a member’s client is never shown a tool it would be refused for. There is no separate permission model to keep in step with the first one.

The same controllers answer JSON to a bearer token, which is why there is no second API quietly falling behind this one. The browser, the CLI, the API and MCP are the same code path.

Signing in

KamalCloud is an OAuth 2.1 provider, with discovery, dynamic client registration and PKCE. An AI client registers itself, opens a browser, and you sign in there. The client is never handed a token you had to copy out of a page.

API tokens are browser-only: they are minted and revoked by a person, in the account’s own screens. An agent cannot create a credential, widen one, or revoke one. Whatever it was given is what it has until somebody changes it.

Before anything expensive

Some tools answer needs_confirmation instead of doing the work. The reply carries a preview of what would happen, and the client has to call again, confirming, before anything proceeds.

The gate is on three kinds of action:

• Costs money – provisioning a server, resizing one, creating a volume
• Cannot be undone – deleting an app, an environment, a server or a backup
• Takes something offline – maintenance mode, stopping an accessory, rebooting a machine

Reading is never gated. An agent can answer questions about the fleet all day without a single confirmation.

Human-approval mode

Confirmation is the agent agreeing with itself. When you want a person in the loop instead, turn on human-approval mode for the install: an API token may then only propose.

Every change becomes a change request in the queue, with the action, the parameters and a description of what it would do, and it waits there until an admin approves or rejects it in the browser. The token that asked and the person who decided are both recorded.

This is the setting to use before handing a token to something you have not watched work yet.

The CLI bridge

The CLI is generic: it reads the tool catalogue and offers one command per tool, so a new action in the application becomes a new command without the CLI being rebuilt. It is standard-library Ruby, with no bundler and no gems.

It also bridges MCP over stdio, for clients that launch a subprocess rather than call a URL, and it can write a Claude Code skill so the tools are described to the model in the shape that client expects.

What this is not

MCP is for a client you are talking to, acting on your behalf while you watch. It is not a scheduled job: nothing here runs on its own, and there is no standing process reading your fleet and forming opinions about it. A tool call happens because something asked for it.