Caelo CMS

@caelo-cms/mcp-server

MCP servers for your Caelo CMS install. Two surfaces, selected by the token's scope:

• `caelo_chat` (default mode, scope chat) — talks to Caelo's own AI agent. You describe an outcome; Caelo's chat-runner does the work.
• Power-MCP (caelo-admin-mcp binary / caelo-mcp-server admin, scope admin) — the full chat-runner tool catalogue exposed directly, so YOUR agent (Claude Code et al.) drives the tool loop and Caelo makes no provider calls of its own. caelo-mcp-server export additionally writes a CLAUDE.md + .claude/skills/ tree generated from the install's live context.

Every mode is a thin shim: calls become HTTPS POSTs against your admin install's /api/mcp/* endpoints, which dispatch into the same chat-runner machinery that powers the live-edit overlay. See the MCP page in the docs for the full Power-MCP working model (work sessions, the shared draft, approval gates).

Install

In your Caelo install:

1. Visit /settings/mcp as an Owner.
2. Click New token, give it a name (claude-code, laptop, ci, etc.), optionally set an AI-spend cap (microcents), and copy the bearer that's shown ONCE.
3. The page shows ready-to-copy setup for Claude Code, Claude Desktop, Codex CLI, Cursor, VS Code and Gemini CLI — a terminal command or a JSON config entry, plus how the client picks it up.

Desktop apps (Claude Desktop, Cursor, VS Code) don't inherit your terminal's PATH: put the full path of bunx (which bunx) into their config instead of the bare name.

ChatGPT and claude.ai in the browser can't use this server: they only connect to MCP servers hosted on the internet (Streamable HTTP + OAuth), and this one runs on your machine over stdio. Tracked in #806.

Manual setup for any other MCP-aware client:

# stdio server invoked by your MCP-aware client

bunx @caelo-cms/mcp-server@latest

It switches to the exact release your install runs at startup (see the MCP page in the docs), so the command never needs a version; @latest keeps bunx from reusing an older cached install.

with these env vars set:

Without CAELO_ADMIN_URL or CAELO_MCP_TOKEN the server still starts and lists its tools (MCP directories inspect servers that way), but every tool call fails and names the variable to set. Power-MCP then lists the catalogue shipped with this release (power-catalogue.json); once configured it always lists your admin's live catalogue, including plugin tools. export exits instead.

Installs behind Google IAP (GCP)

On gcp and gcp-firebase installs the admin sits behind Identity-Aware Proxy, which rejects every request before Caelo sees it unless it carries a Google credential. With CAELO_IAP_SERVICE_ACCOUNT set, the server signs a short-lived JWT as that service account (IAM Credentials signJwt, using your Application Default Credentials) and sends it in Authorization next to x-caelo-mcp-token: IAP checks the first, Caelo the second.

One-time setup on your machine:

gcloud auth application-default login

The provisioner creates the service account (caelo-mcp@ ), allowlists it on IAP and lets everyone on the IAP allowlist sign as it — on new installs via Pulumi, on existing ones during cms-provision upgrade. No service-account keys are involved.

The caelo_chat tool

Output: assistant reply text + a JSON block with chatSessionId (for the next call), requestId (click through to /settings/audit/ for the full audit trail), the structured tool-call summaries the agent dispatched, the per-turn cost in microcents, and a pendingProposals count so the agent can surface "you have N things waiting for Owner approval".

Why route editing through chat?

Browse / publish / propose actions happen *through* the chat — "which pages exist?" → the Caelo agent calls pages.list internally → answers in text. Same auth surface, same RLS scoping, same audit trail, same propose-execute Owner gate as the browser. The remote agent talks to a human-equivalent agent, not to a programmatic API.

License

MPL-2.0.

Image uploads

Both modes expose caelo_upload_images. For example, call it with:

{"images":[{"filePath":"/home/me/Pictures/character.png","alt":"Main character reference"}]}

Paths are local to the MCP process. Alternatively use base64 plus an optional filename; supply exactly one of filePath and base64. Uploads support PNG/JPEG/WebP/GIF, up to 5 MiB each, with at most four files per call. The result contains per-file successes/errors and an attachments array. Pass that array to caelo_chat alongside message to send actual image content to Caelo's AI. In admin mode, the returned asset IDs can be used with regular media/page tools.

The token owner's current content.write permission is required for either scope. Images are stored in the shared CMS media library; admin previews require authentication. Uploading alone does not publish a page. A partial batch keeps successful uploads — retry only the failed entries. See the MCP page in the docs for HTTP examples and server limits.