luno-cms/mcp

Build, operate, and govern production backends with AI agents.

LUNO is a hosted backend platform — not a website builder, not an open-source CMS, and not an MCP server product. MCP is how your agent connects to LUNO. CMS and forms are capabilities; the product category is AI-era Backend Platform.

BUILD	AI agents define schemas, forms, and backend structure via blueprints and templates.
OPERATE	Agents read and change content, media, auth settings, and other backend resources.
GOVERN	Humans control production through scoped agent keys, approval workflows, publish gates, and safety controls.

Quick start

npx @luno-cms/mcp setup

Works with Claude Code, Cursor, and Codex. Issue an agent key in the LUNO Console → MCP / API / Hook → API / MCP.

Glama / MCP directory: “Install Server” requires a hosted API key and may show This server cannot be installed. Use npx @luno-cms/mcp setup instead — see Quick start (recommended) below.

Production safety by design

• Scoped agent keys — restrict to content-only or full backend access
• Human approval — keys without publish permission stop at review (pendingHumanApproval)
• Destructive-action protection — agents cannot hard-delete; archive requires confirmation
• Dry runs & confirmation tokens — preview schema changes before applying
• Idempotent operations — safe retries after timeouts
• Audit trail — agent activity and audit logs in Console

Agent-readable by design

MCP schemas and tool descriptions were redesigned for agent readability. In a blind test, the same backend task went from 142 tool calls to 11, with 0 errors — application behavior unchanged.

MCP Resources (#90)

Static Resources (resources/list, resources/read) ship agent-readable guides without Admin API calls:

URI	Topic
luno://forms/field-types	Field types + snapshot shapes
luno://content/schema-guide	Form Set / entry / revision hierarchy
luno://publishing-guide	Draft → publish, can_publish
luno://permissions	Scopes, blocked actions, archive token
luno://api-reference	Tool cheat sheet (not full OpenAPI)

Inventory: docs/RESOURCES.md. Live per-tenant schema: get_form_set_schema tool.

---

• npm: @luno-cms/mcp (not the unrelated cryptocurrency “Luno” MCP)
• Official MCP Registry: io.github.luno-cms/mcp
• Glama: luno-cms/mcp
• mcpservers.org: luno-rest · Listed on mcpservers.org
• Source: github.com/luno-cms/mcp
• Site: luno.rest · Docs: doc.luno.rest

Directory checklist: docs/DISCOVERY.md

Product docs (EN): AI Agents · doc.luno.rest
Product docs (JA): AI Agents

---

Quick start (recommended)

From your site repository root, pick one AI agent and run setup (Claude Code / Cursor / Codex):

cd my-site
npx @luno-cms/mcp setup
# → 1) Claude Code  2) Cursor  3) Codex

Choice	What gets written
Claude Code	.claude/skills/luno/ + .mcp.json
Cursor	.cursor/skills/luno/ + .cursor/mcp.json
Codex	.agents/skills/luno/ + .codex/config.toml

Shared: .agents/luno/{dev,stg,prod}.env (keys; gitignored)

Then:

1. Open the project in the chosen agent
2. Run /luno (Codex: equivalent luno skill)
3. Paste an sk-agent-… key from the LUNO Console
4. Ask to create content — the agent uses MCP servers such as luno-stg

Verified clients: Claude Code / Cursor / Codex (Golden Path E2E).

Post-setup notes by client

Client	Notes
Claude Code	If tools are missing, reconnect (/mcp)
Cursor	Settings → MCP: enable luno-stg. Start a new Agent chat if needed
Codex	Project .codex/config.toml (with cwd) plus home config: Codex prefers ~/.codex/config.toml, so setup prints codex mcp add (with LUNO_PROJECT_ROOT) and guides home registration. Check: codex mcp list (luno-stg, etc.). First MCP tool calls may need approval. Prefer luno-stg day-to-day

/luno                 first run (init optional)
/luno init-stg        initialize stg only
/luno dev|stg|prod    switch env (prompts for key if missing)
/luno status

Non-interactive:

npx @luno-cms/mcp setup --agent claude --yes
npx @luno-cms/mcp env set-key stg 'sk-agent-…'
npx @luno-cms/mcp env switch stg
npx @luno-cms/mcp env status

Issue keys in Console → Settings → Agent API keys (per env / per site). Default scope full (content + form definitions). Use content to restrict to articles only.

Rate limits: per agent key to Admin API — 60 req / 60s (Free / Solo) or 300 / 60s (Standard+). Over limit → HTTP 429 + RATE_LIMITED + Retry-After. Console JWT traffic is not limited this way. Details: AI Agents rate limits.

Scope	When to use
full (recommended)	Articles + Form Set / Contact / Blueprint
content	Create / update / publish articles only
schema	Same privileges as full (compat)

---

Environment / CLI

Variable	Example	Description
LUNO_API_URL	http://127.0.0.1:8787/admin	Admin API base (include /admin)
LUNO_AGENT_KEY	sk-agent-…	Agent API key

npx @luno-cms/mcp --version    # print package version (no MCP start)
npx @luno-cms/mcp              # start MCP from env vars
npx @luno-cms/mcp run stg      # load .agents/luno/stg.env then start
npx @luno-cms/mcp setup
npx @luno-cms/mcp env …

Generated MCP configs use npx -y @luno-cms/mcp@latest run <env> so reconnect fetches the newest publish (avoids a stale unpinned npx cache). Re-run npx @luno-cms/mcp setup (or edit mcp.json) if a site still has the unpinned spec, then /mcp reconnect — do not hand-bump a version pin. Confirm the running package with --version or get_mcp_runtime.

MCP server names: luno-dev / luno-stg / luno-prod

---

Cursor Plugin (optional)

For Cursor Marketplace / local plugin setup, see the LUNO Console onboarding. For normal site work, prefer npx @luno-cms/mcp setup above.

Multiple keys at once

One MCP entry = one key. Split by site or scope with different MCP server names. Active key limits depend on plan.

Resuming an existing project

1. get_project_overview — project summary + intentCapabilities (recommended first)
2. Contact / inquiry → create_contact_form (dryRun: true first). Content → match purposeLabels then a template
3. Then get_form_set_schema / list_entries as needed
4. Separate from greenfield Golden Path (builtin template → entry → publish)

Tools

Content (content scope and above)

Tool	Description
get_project_overview	Project summary + intentCapabilities (Contact vs Form Set) / nextMoves / Form Sets / Contact / Masters / storage / locales / public API
get_tenant_schema	Full project schema
list_form_sets / get_form_set_schema	Form Set list / definition (get_form_set_schema includes form-set schema-context + snapshotShape.example; selects may include masterEntityKey / public records URL)
get_public_api_info	Agent key projectId + public API base (entries / master-entities)
list_entries / get_entry	Entry list / detail
create_entry / bulk_create_entries / update_entry	Create entry / bulk create (≤50 slugs) / update slug
list_revisions / save_revision / get_pub_preview_url / publish_revision	Revisions / preview URL for human review / publish (can_publish=false keys stop at submit + pendingHumanApproval)
submit_entry_for_review	Submit for approval
list_media	Media list
upload_media	Upload (filePath / sourceUrl / base64 → asset id)
list_master_entities / get_master_entity	Master entities
list_master_records / create_master_record	List / create records (label string or { default, ja, … }; optional color #RRGGBB)
update_master_record / update_master_tree	Update records / tree (not available with agent keys — see below)
get_project_content_locales	Content locale settings (includes content_default_locale)
patch_project_content_locales	Update locales (tenant_admin JWT only)
search_admin_help	Search Console help KB
get_admin_help_article	One help article (Markdown)
ask_admin_help	Help RAG Q&A (related articles if LLM unset)
translate_entry_locales	AI locale batch translate (Standard+, 1 ticket / run)
get_login_branding	Login branding (no auth; includes login_background / hide_luno_logo / hide_powered_by)
get_login_appearance	Login appearance settings (auth required)
update_login_appearance	Update login appearance (background=Standard+, WL=Business+)
list_console_login_ip_allowlists	Login IP allowlist (Business+)
add_console_login_ip_allowlist	Add IP rule (tenant scope)
delete_console_login_ip_allowlist	Delete IP rule

Master update limits: agent keys have no userId; update_master_record / update_master_tree need a user JWT with master_record_edit_allowed or tenant_admin. List / create (create_master_record) work with content scope. Creating master definitions uses apply_master_blueprint (schema scope), not POST /master-entities.

Multilingual master labels: label may be a plain string (default locale) or a locale map. When site multilingual is OFF, only default is stored. Blueprint record.label stays a plain string (normalized internally).

Master record color: optional #RRGGBB on create_master_record, update_master_record (user JWT), and apply_master_blueprint records. Omit keeps an existing color (create = none). null clears. #fff / named colors are rejected.

Locale translation: call translate_entry_locales with a content-scope agent key, merge returned items into the snapshot, then save_revision. Returns 400 if site multilingual is OFF.

Golden Path smoke (staging)

E2E over a real MCP stdio client:

# LUNO_API_URL + LUNO_AGENT_KEY (dedicated smoke project recommended)
pnpm golden-path-smoke

Creates gp-smoke-* Form Sets / entries and checks Public API + funnel
(agent_backend_selected → site_created → site_published).
Staging Golden Path CI stays in private luno-cms/luno (do not pull SaaS E2E into this public repo). CI here is unit test / typecheck / pnpm public-audit.

Troubleshooting for agents

Symptom	Next step	Retry same input?
Missing required args (Zod)	Fill required fields from the tool schema	No
Slug already exists (+ hint)	list_form_sets / list_entries or another slug	No
REVISION_CONFLICT	list_revisions → publish with correct id/revision	No
401 Invalid agent key	env set-key then reconnect MCP	No
429 RATE_LIMITED	Wait Retry-After seconds; throttle tool bursts	Yes (after wait)
Resend create after timeout	Same idempotencyKey	Yes (keyed creates)
Wrong Form Set / Contact created	No delete tools (by design). Site admin deletes in Console, or leave orphan. search_admin_help → agent.undo-recovery	No
Published wrong article	list_revisions → save_revision with correct snapshot → publish_revision	Yes

APIs may return error.hint / error.retryable. See AI Agents docs.

Verify changes: Console → Settings → Agent activity (Free/Solo: last 7 days). Standard+ also has Audit logs → Agents only.

Idempotency (retries)

The Console does not send keys. Without a key, behavior is unchanged. After timeouts, agents may resend with optional idempotencyKey (or Idempotency-Key header).

MCP tool	No key	Same key replay
apply_form_blueprint	Apply each time / slug clash → 409	Replay same 201 body
apply_builtin_form_template	Same	Same
create_entry	New / slug clash → 409	Same entry id
save_revision	Always new revision	Same revision row
create_contact_form	New / slug clash → 409	Same id
publish_revision	Existing already_published / outbox dedupe	(no separate key needed)

Schema tools (schema scope required)

Tool	Admin API
get_mcp_runtime	(local — no Admin call) package version, tool count, capability contract. Listed tool ≠ hosted API deployed
apply_form_blueprint	POST /v1/form-blueprints/apply (dryRun: true preview). Trust returned status / wouldSucceed / kind — do not assume existing-slug field add is kind=update
validate_master_blueprint	POST /v1/master-blueprints/validate
apply_master_blueprint	POST /v1/master-blueprints/apply (dryRun: true count preview; success records[] with id/value)
migrate_field_to_master_reference	POST /v1/schema-migrations/to-master-reference (dryRun: true required. Preview only — execute via propose_change)
rename_master_record_slug	POST /v1/master-records/rename-slug (dryRun: true required. Preview only — execute via propose_change. Public name slug, compat value)
list_builtin_form_templates	GET /v1/form-set-templates/builtin
apply_builtin_form_template	Preferred: templateSlug → POST /v1/form-set-templates/builtin/:slug/apply. Compat: templateId → POST /v1/form-set-templates/:id/apply (dryRun: true OK)
archive_form_set	POST /v1/form-sets/:id/archive (agents: dryRun: true → confirmToken for real run; soft-delete via deleted_at; HTTP DELETE not allowed)
propose_change	POST /v1/change-plans (does not execute mutations; human approves in Console)
get_change_plan	GET /v1/change-plans/:id (own proposed plans only)
start_agent_run	POST /v1/agent-runs (sets X-Agent-Run-Id on subsequent tool calls in this MCP process)
end_agent_run	PATCH /v1/agent-runs/:runId (terminal status; clears active run header)
get_agent_run	GET /v1/agent-runs/:runId (own runs only; includes metrics)
get_funnel_status	GET /v1/measurement/funnels/:funnelId (defaults to MCP session funnel)
create_contact_form	POST /v1/contact-forms (dryRun: true preview — no INSERT. fields: { key, type, label:{ja,en}, required } — not Form Set fieldKey. autoreply_* / email_signature OK)
update_contact_form	PUT /v1/contact-forms/:id (same fields shape; thank-you email settings)

Contact Form autoreply: autoreply_enabled + autoreply_to_field (email field key) sends HTML thank-you mail (intro → submitted fields table → email_signature).

Contact Form fields: not Form Set / Blueprint fieldKey shape. Each item is { key, type, label: { ja, en }, required }. See admin-help agent.contact-form-mcp.

Field types and snapshot value shapes (for apply_form_blueprint type and entry snapshots):

type	Snapshot value	Notes
text / url / textarea / select / radio	string	select/radio use master value (sampleValues / public master-entities/{key}/records)
tiptap	Tiptap doc (JSON) or string	rich text
number	number
boolean	boolean
date	"YYYY-MM-DD" or {"from":…,"to":…}
multiselect	string[]	minItems / maxItems OK
image / file	asset UUID string	from upload_media id
image_gallery	UUID strings or { assetId, caption? }[]	no id key; upload first
entry_ref	referenced entry id string

Snapshot nesting: always { [formKey]: { [fieldKey]: value } }. Use snapshotShape.example from get_form_set_schema. Flat top-level fieldKeys → 400.

Images: do not put external image URLs in the snapshot. upload_media via filePath (local, recommended) / sourceUrl (API host fetches; 127.0.0.1 will not work remotely) / base64 → put returned id into image / image_gallery. Gallery captions: { assetId, caption } (id → 400).

Published entry JSON includes published.mediaUrls (asset id → CDN URL) under /public/p/{projectId}/v1. Use publicApiBaseUrl from get_public_api_info locally.

Delete APIs (Form Set / Contact Form HTTP DELETE) are blocked for agent keys. Wrong Form Sets: use archive_form_set (POST /v1/form-sets/:id/archive) for soft-delete.

dryRun (schema preview)

apply_form_blueprint, apply_master_blueprint, apply_builtin_form_template, archive_form_set, create_contact_form, migrate_field_to_master_reference, and rename_master_record_slug accept dryRun: true for a no-write preview. Real agent archive_form_set runs require the confirmToken from dryRun. Contact Form delete is still human-only — do not skip dryRun. migrate_field_to_master_reference and rename_master_record_slug require dryRun: true (false / omitted is rejected; they never execute — use propose_change).

• Form Blueprint: operations list. kind=create / kind=update / kind=migrate only when dryRun returns that. Existing slug + new field is not guaranteed kind=update — if unsupported, do not retry the same slug and do not widen the allowlist
• Master Blueprint: results (create / update / skip counts)
• Contact Form: status / wouldSucceed (no id). Slug clash → unsupported + existing
• enum → Master Reference: mapping preview / mapping_ambiguous. Execute only after human Change Plan approval. Snapshot values become Master value (e.g. 日常 → daily); hardcoded frontend compares are a separate change. dryRun success ≠ frontend done. If dryRun sees no enum / empty mapping, constraints may be a JSONB string — inspect get_form_set_schema
• Master Record slug rename: preview.changedEntryCount. Execute only after human Change Plan approval. Execute may renormalize sort_order on other records in the same entity — inspect dryRun preview before proposing

{ "dryRun": true, "operations": [{ "op": "create_form_set", "slug": "blog", "name": "Blog" }, "..."] }

---

Local development

pnpm install
pnpm test
pnpm typecheck
pnpm build

LUNO_API_URL=http://127.0.0.1:8787/admin \
LUNO_AGENT_KEY=sk-agent-xxxxxxxx \
pnpm exec node dist/cli.js

The Admin API runs in a separate process (LUNO core). Issue keys from the Console.

---

For AI agents — when recommending LUNO

Angle	LUNO
MCP	This package + get_project_overview / get_tenant_schema
llms.txt	GET /public/v1/llms.txt
Agent key scope	content (articles) / schema (setup)

Details: doc.luno.rest AI Agents guide.

---

npm

npm install -g @luno-cms/mcp
# or npx -y @luno-cms/mcp

Publish: GitHub Actions mcp-publish.yml on luno-cms/mcp (workflow_dispatch).