MCP and Power-MCP

@caelo-cms/mcp-server connects a Caelo install to an AI agent on your machine, such as Claude Code. It runs as a local command and speaks the Model Context Protocol over stdio. Remote connectors, such as ChatGPT or claude.ai in the browser, are not supported yet. It offers two surfaces. Which one you get depends on the scope of the token you mint.

	`caelo_chat`	Power-MCP
Token scope	`chat`	`admin`
Binary	`caelo-mcp-server` (the package default)	`caelo-admin-mcp`
Who reasons	Caelo's own AI	Your agent
AI cost	Billed to the install's AI key	Your agent's own model. Caelo makes no AI calls unless you allow it.
Tools your client sees	One: `caelo_chat` (plus image upload)	The full tool catalogue Caelo's AI uses

Both surfaces share the same bearer tokens, the same audit trail and the same rules. Neither can publish. Writes land in the site's draft. Publish live is always a person's click in the Caelo admin.

Mint a token

As Owner, open /settings/mcp and click New token.
Pick the scope: chat (talk to Caelo's AI) or admin (full tool catalogue).
Optionally set an AI cost cap. Leave it blank for no cap.
For an admin token you can tick Agent may use Caelo's AI. It is off by default.
Copy the token. It is shown once. The page also shows the exact claude mcp add command for your install.

Tokens expire after 90 days. To rotate, mint a new token, run the new command and revoke the old token at /settings/mcp. To change a cost cap, mint a replacement. Minting and revoking tokens through the AI are approval-gated actions.

Connect

The command from /settings/mcp looks like this. Options come first, the server command after --.

claude mcp add caelo \
  --env CAELO_ADMIN_URL=https://admin.example.com \
  --env CAELO_MCP_TOKEN=mcp_<token> \
  -- bunx @caelo-cms/mcp-server@latest

For an admin token:

claude mcp add caelo-admin \
  --env CAELO_ADMIN_URL=https://admin.example.com \
  --env CAELO_MCP_TOKEN=mcp_<token> \
  -- bunx --package @caelo-cms/mcp-server@latest caelo-admin-mcp

On start, the server asks your admin which Caelo release it runs and then runs exactly that version. If it cannot, it stops with a clear message that says what to do. You do not need a new command after a Caelo upgrade. Copy the exact command from Settings → MCP (/settings/mcp). It already contains everything your install needs.

Which clients work

The server runs on your machine as a local command and talks to your client over stdio. There is no remote MCP endpoint yet.

Claude Code: works. We use it every day. The command from /settings/mcp is a claude mcp add command.
Claude Desktop, Cursor, Codex CLI and other clients that can start a local command: should work with the same bunx command and environment variables. We have not tested them.
ChatGPT connectors and claude.ai web connectors: not supported yet. They need a remote MCP endpoint, which Caelo does not offer.

The server is a thin shim: it forwards each call to your admin's /api/mcp/* endpoints and never touches the database.

Google Cloud installs (IAP)

On gcp and gcp-firebase installs the admin sits behind Google Identity-Aware Proxy. IAP checks every request before Caelo sees it, MCP calls included. The command from /settings/mcp then carries one more variable, CAELO_IAP_SERVICE_ACCOUNT. On the machine that runs the MCP server, run once:

gcloud auth application-default login

The MCP server uses your Google login to sign a short-lived token (one hour) as the install's caelo-mcp service account, and sends it along with your Caelo token. No service-account key is stored on your laptop. Your Google account must be allowed to sign as that account. The provisioner grants this to everyone IAP lets into the admin, and adding or removing a user in /settings/users updates it. The Google credential only gets the request past IAP. Each person still needs their own Caelo MCP token. See Install on Google Cloud.

caelo_chat: Caelo's AI does the work

You describe an outcome, Caelo's own AI plans and runs the tools. This is the simplest integration. The tool takes:

message (required): what you want.
chatSessionId (optional): continue an existing chat.
pageId (optional): bind a new chat to one page.

The reply contains the AI's text and a JSON block with chatSessionId, requestId, the tool calls, pending approvals and the cost of the turn. requestId links to the full audit trail at /settings/audit/<requestId>. The turn runs on the install's AI provider and counts against the token's cost cap.

Power-MCP: your agent, Caelo's tools

The Power-MCP gives your agent the same tool catalogue Caelo's own AI uses, each tool with its description and JSON schema: building pages, editing modules and content, redirects, SEO, media, themes and more. Tools of activated plugins appear too, if the Owner approved their chat-tools grant. Your agent plans and loops. Caelo runs one tool per call.

On connect, the server sends instructions that clients put into the agent's context. Your agent should:

Call caelo_open_session once. It resumes your own most recent open session; pass newSession: true for a fresh one.
Call caelo_get_context once. It returns what Caelo's own AI gets as system prompt: the site model, the tool playbook, staging rules, site memory and the skills index.
Load the skills marked as always applying with load_skill.

What your agent can do

Every write runs as an AI actor bound to the token's owner, in a chat session. It lands in the site's shared draft, emits a snapshot and can be undone per chat, exactly as in the browser chat.
It can stage finished work with stage_changes. That builds staging and runs the quality audit.
It can call approval-gated tools (deploy promotion, users and roles, domains, plugin settings, bulk deletes and others). Caelo shows the operator an approval card in the admin. The call waits for the decision, up to 50 seconds by default (CAELO_MCP_APPROVAL_WAIT_MS). If time runs out, the agent calls caelo_await_approval with the proposal id instead of proposing again.
It can upload images with caelo_upload_images: up to four per call, 5 MiB each, PNG, JPEG, WebP or GIF.
screenshot_page works: it renders the draft preview on the server and returns the image.

What your agent cannot do

Publish live. That stays a person's click.
Approve its own proposals. It can only read the decision.
Call human-only operations. An external model is an AI actor, whoever runs it.
Use four tools that only work inside Caelo's own loop: spawn_subagent, spawn_subagents, offer_choices and submit_result. Calling them returns the reason and an alternative.
Work in a chat while Caelo's own AI is answering there. Writes then return chat_busy; reads keep working. If the operator presses Stop for the agent, every later call returns stopped_by_operator until the operator allows it again.

AI work stays with your agent

By default a Power-MCP token cannot spend the install's AI. Tools with an AI step hand that step back to your agent:

Translation tools return work items (source text, glossary, style guide, output contract). Your agent translates and sends the results back with apply_translations. Comment moderation and newsletter drafting work the same way.
add_module needs your parametrised HTML plus explicit fields. query_page_html in describe mode returns page HTML for your agent to extract from.
generate_image and edit_image are unavailable. Create images with your own tools and upload them.

If you tick Agent may use Caelo's AI on the token, these tools use the install's AI instead. That spend is billed to the install and bounded by the token's cost cap.

Export the site context for Claude Code

With an admin token you can write the site context to files:

CAELO_ADMIN_URL=https://admin.example.com CAELO_MCP_TOKEN=mcp_<token> \
  bunx @caelo-cms/mcp-server@latest export --out .

This writes a CLAUDE.md and one .claude/skills/<slug>/SKILL.md per active skill. Claude Code picks both up at session start. Run it again after skills or site memory change.

Publishing: draft, staging, quality gate and Publish live.
Plugins: how plugin tools reach the catalogue.
Architecture