Keys and the MCP
The full access model. Who can do what tells it for an owner; this page is for whoever configures keys or connects a tool.
The actor file
A key belongs to an actor: a file in the scope’s .actors/ folder, kept with the site’s history. Three columns: who (identifier), what may be written (can: a list of rights), how they come in (keys: public keys, token hashes — the raw token lives only in the client, shown once — or an authenticator secret, the second proof a browser session gives before it may write). Fail-closed per scope: an empty .actors/ answers 401 to every read and write (only the protocol’s discovery is open). “Editor” and “owner” are colloquial, not types: no roles, wildcards or aliases; an unknown string never matches.
The file model of rights
Every right is one cell, <object>.<bit>, with bits read, write, delete. Bits are independent: no cell implies another; write-without-read is valid (deliver without seeing).
| object | .read |
.write |
.delete |
|---|---|---|---|
data |
read live and draft | stage | discard |
theme |
see the source — reveals implementation, grants no code trust | stage (trust: executable PHP — de facto the whole site; never to a semi-trusted key) | discard |
assets |
read live and draft | stage (via the file lane) — script trust as soon as a theme loads a .js/.css from assets/: the file replaces what the browser runs |
discard |
guide |
read the site’s own knowledge — flat markdown, never served; a key without it sees the root named in the map (may: []) but nothing inside it |
stage a page (co-writing the rules) | discard |
live |
free in a public scope; a real grant in a non-public one | publish — going live is writing the live layer | unpublish — reversible removal, kept apart on purpose: most publishing keys fill the site, never empty it |
plan |
limits and current usage | reserved | reserved |
journal |
the change timeline | reserved | — |
inbox |
what the site received — grant sparingly, personal data | reserved | — |
actors |
view the field | add, set, token, invite, drop — within the subset rule and management scope | reserved |
Composition per target: publish = live.write + the target root’s write bit; unpublish = live.delete + the root’s write bit (the demotion writes the draft) — you approve and retract only over roots you may write. The delete bit removes from the object: on the roots it gates discard (the sole destroyer, draft layer only), on live it gates unpublish. Overwriting within a layer is write; removing a live record for good is unpublish, then discard. Minting: read generously, write along the working role, delete never by default. A refusal names the missing cell.
A write-only key stages blind. The preview overlays the whole staged site, so it rides on data.read; without it a key still stages but gets no preview URL, and audit messages in its response are redacted to its own targets.
Delegation
Viewing rides on actors.read, unbounded within that bit so an auditor key can survey without mutation power. Add, set, token and drop ride on actors.write, bounded two ways — subset rule: hand out only rights you carry; management scope: mutate only actors whose rights fall within yours. Every change is journalled; a token is a one-shot secret. Self-service issuance to strangers stays out — it would rebuild the identity middle layer.
Token discipline
An actor may carry an address (email; actors add / set take it with consent: true — the caller’s word that the person agreed, dated on the file as emailConsent; set email: null clears both; one actor per address in a scope). It is a door, never identity: actors invite mails a one-shot link (/edit#invite=<token> — in the fragment, so no server log or referrer sees it; a blinded transit file, ten minutes, gone on first use, one per address per minute) that opens a reading session in the edit client and, being the owner’s, lets the person enrol the first authenticator on Unlock; the door itself takes an address (POST {email}, JSON only) and answers the same whether it knows it or not — the mail tells — and that link reads only. An actors view shows the address to actors.write alone. actors drop with type (token · totp) takes one kind under a label; an authenticator reset takes the proof of every session with it. The address lives in the actor file like the rest, in scope. A token is shown once; the file keeps the hash. An authenticator secret (enrolled by the person on the edit door’s Unlock, or provisioned by CTXR when none exists yet) is kept as it is — an authenticator needs the shared secret, a hash would not do. It is a second factor and opens nothing on its own: the key it accompanies is never at rest anywhere. The folder’s boundary is CTXR’s private store. Same label = replace, the old codes die at once. Rotate on a schedule and at once on suspicion; drop keys the day a person or integration leaves. Two lower-trust forms for clients that cannot send a header: the ?key= capability URL (it lands in access logs — rotatable, used sparingly) and the one-shot links the MCP mints (upload URL, pack download, report), where the token is the capability, bound to one file, dying on use or TTL — and, for an upload link, with the rotation of the key that minted it.
Every token the engine mints — an actor’s key, a session, a one-shot link, a draft preview — comes from one recipe, secret_token (secret.php): 16 bytes of CSPRNG as hex, 32 for a session. Apart from those stands the site secret: 32 bytes set once when the site is stood up, the key under secret_sign (a readable link nobody can alter) and secret_seal (a value nobody can read). Rotating it replaces it and voids every tag and packet made before — say so to whoever holds a signed link. Without it those verbs answer null; nothing falls back to a weaker key.
The MCP
The MCP endpoint is one route in three shapes: MCP for Claude-class clients, REST/JSON for a direct caller, OpenAPI discovery for tools that read that form. Three lanes beside it: file (/mcp/file — PUT one file in, GET an asset out), pack (/mcp/pack — a zip out with a one-shot link, or bulk in to drafts), report (/mcp/report, GET only — the one-shot download of a full audit report when more messages than fit inline). Authentication: a Bearer header or the capability URL; rights are checked per verb and per target root. Every write is staged and checked — it passes the scope check and the plan envelope before it reaches the draft layer — never straight to draft or live.
The verbs
Nineteen, in four families — read, write, layer, manage, in that order below; the aliases browse, promote, demote, rename resolve onto them.
| Verb | What |
|---|---|
fetch |
a file, or a listing (folder prefix; empty for the map: every root named with may — the bits this key holds there — plus docs, and the reading order as notes; the same folders search takes as in); a data listing carries the way to the index (find: llms.txt, query: /data.json?q=), a data-type listing the type’s own index (dataset) and its field schema, a theme listing the docs to read first (docs/theme); docs, docs/<section> and docs/<path>.md read the engine documentation; the response names the layer returned and the layers that exist; a folder listing is paged (limit, default 500, max 2000; has_more + cursor for the next page; matched counts the whole folder; a type’s schema rides the first page); deep: true lists every file below the folder instead, flat — its name the path relative to the folder, paged the same way; order: "newest" puts the last change first (live or draft, whichever is later) instead of by name — a cursor belongs to its kind of listing, and a newest cursor whose file changed answers conflict; an asset entry carries mime (its type by extension; an svg holding a <font> reads font/svg) and used (how many live things name it) and an asset file used_by (target, name, and url where the thing is a page) — read from the live content: a path that starts /assets/, the site’s origin taken off, a query ignored |
search |
{ query, in, layer, lang, limit, cursor } — the answer opposite fetch: fetch reads one file, search reads a root. With words: ranked hits from one root — in: "data" (the content, default), "docs" (how CTXR works), "theme", "assets" or "guide" (the scope’s files, behind that root’s read bit) — in tiers: an exact phrase, then names and identifiers (docs: titles), then descriptions (abstracts), then bodies; a lower tier never outweighs a higher one. A data hit is @type, identifier (the file: fetch data/<type>/<identifier>.json, or read /data/<type>/<identifier>.md), name and a snippet, with @id and url only where the entity is a page or an anchor — never a body; and urls — the same search as an address (self, its .md twin, next while there is more). A docs hit is the page’s identifier (its fetch target, docs/<path>.md), section, headline and a snippet; a theme, assets or guide hit the file’s identifier (its fetch target), section (the folder it sits in) and a snippet — an asset by name only, never its bytes. layer picks the layer searched: live (default — what the site serves, and the only layer ?q= knows), draft (the staged round alone) or both (live and draft together, a staged version winning over its live one — the rule of the draft layer everywhere); every hit says its layers (["draft"] new, ["draft","live"] staged over live, ["live"]), and draft/both read with the root’s read bit (data.read for data — the same right fetch layer:"draft" asks); the docs have one layer. lang picks the language searched (in: "data" only; default the site’s main language). A query needs at least three characters — one or two are refused (invalid_argument; /data*?q= answers 400), never searched or cached. Paged with limit (20, at most 50) and an opaque cursor (has_more) that belongs to its words, root, type or section, language and layer — anywhere else invalid_argument, after a publish conflict. Without words: the map — start (llms.txt), on a multilingual site languages and the per-language indexes, and then: the docs (how to search and fetch them), the index as data and data_md, the sitemap. One motor serves the MCP and the /data* URLs, so search and ?q= never disagree |
drafts |
what is staged, with the round’s preview URL and per page-claiming entry its staged preview |
diff |
a staged draft against live |
download |
the GET URL for an asset; when a replacement of a live asset is staged, a draft_url for the staged bytes as well — the site preview overlays new assets only, not replacements |
plan · journal · inbox |
the meta region, each behind its own read cell (an auditor’s key can be exactly that): limits and current usage; the change timeline, filterable by actor, action, target and time; what the site received per kind, an overview when no kind is given |
create · update |
stage; a page-claiming target returns its staged preview per language |
upload |
mint a one-shot PUT URL for one binary target you may write |
pack |
bulk in or out |
publish |
one target, a list (audited together as one scope; moved per file — the result lists what went live), a prefix (every staged draft under it — the root’s write bit is asked before the MCP looks, so a key without it gets missing_right, never “nothing staged”), or all:true for the whole round (required when no target is passed) |
unpublish |
one path or a list only — retiring is never bulk; the project layer (theme/config.php, functions.php, index.php, templates/index.php) and the organisation entity are refused at the door: they never leave live, change them with update and publish. It takes any existing name within the roots, also one the door (create, update, pack) no longer admits — an old spelling never gets stuck; for such a name the answer says that publish will not take it back: discard it, then create it under a clean name |
discard |
drop a draft — one path, a list, a prefix (the root’s delete bit first, as with publish) or all:true; like unpublish it takes any existing name within the roots, not only what the door admits |
validate |
what publish would say, without writing: the same scope (a target — one path, a list, a prefix — or none for the whole round, as publish all:true), the same checks per target, the same audit; only live.write is not asked |
delete · move |
instructive: change nothing (changed:false), return the steps for your target — delete is unpublish then discard, the steps following the target’s actual layers when your key holds the root’s read bit (otherwise the general recipe); a page moves by changing its slug, a file under another path is a new file |
actors |
view, add, set, token, drop; a key’s label (it lands in the journal and the listings) is 1–64 characters — letters, digits, space, . : @ _ - — else invalid_argument |
create, update, publish, unpublish and discard take an optional note — what was asked, in the caller’s words, up to 280 characters — that lands on the journal line; without one the MCP journals actor, verb and target. initialize carries instructions: the live/draft model and the lanes on one page. Everything an agent sees — descriptions, errors, journal lines, OpenAPI, audit messages — is English.
The docs through the MCP
The engine’s documentation — these pages — is a root of its own behind the MCP, and the one root without a bit: every key reads it, none writes it, and it has one layer (layer: "draft" answers not_found). It is the contract, so it is never withheld; and it is never served at a URL by a site fetch "docs" lists every page with its section, headline and abstract; fetch "docs/<section>" one section; fetch "docs/<path>.md" returns the page as markdown; search { in: "docs", query } finds the page about something. The docs travel with the engine, so what an agent reads is what the version it is talking to does. The site’s own rules are not here but in guide/, behind guide.read. The reading order an agent follows: the MCP, then guide/, then the docs, then the index (/data.json, /data.md), then the sitemap — the same ladder search without words hands back.
What the MCP does not do, so no call is spent finding out: no shell, no fetching of URLs on your behalf (page and projection URLs are plain web addresses — open them or hand them to your human), no editing of a binary in place (download, change, upload), no rename or move (see move), no search engine beyond the site’s own roots (search matches words in what the site holds, nothing on the web), never a bulk unpublish.
The envelope
Every answer — verb or lane, success or refusal — is one object, so an agent reads it and a client branches on it:
ok bool did the verb do what it promises (validate: the audit ran)
code string always — one of the closed set below; the reason behind ok
error string only when ok is false — the sentence
result object data, also on a refusal (the blocking report, what did go through, the refused entries); never prose
note string[] what to do next — lifecycle, redirect, reading order
advisory string[] what to know, blocks nothing — warnings, truncation, untrusted input, a journal line that could not be written
result is always an object ({} when there is nothing to say), voice lists are absent when empty, and prose never sits inside result — a URL is data, how to read it is a note. On a refusal result still carries the honest state: audit (the report that blocked), published[] / unpublished[] / discarded[] / staged[] plus failed on a partial, failures[] on a scope refusal, need on a missing right, layers on a layer miss, types on an unknown data type. Collections are lists of objects with the identity as a field (drafts, entries, kinds, languages), sizes are bytes, moments are ISO 8601 with offset (modified, at, expires), write outcomes are past-tense lists even for one target.
A blank verb is an instruction house. A verb called without the thing it acts on does not fail — it answers ok with the map as data and the next step as notes: fetch with an empty target names every root of the scope (with may, the bits your key holds there) and docs; search without words names the indexes and the reading order; delete, move and upload return the steps that do what was meant. The same shape every time, so an agent whose client caches an old tool list still learns the next move from the answer itself — search { in: "<root>" } over the folders fetch just listed. Nothing changes in an instruction house (changed: false where a change could have been expected).
The codes, closed — a client branches on these, and REST maps them to the status:
| code | meaning | REST |
|---|---|---|
ok |
done | 200 |
partial |
a set failed halfway; result says what did go through |
500 |
no_rights |
the key holds no right at all (or none was offered) | 403 |
missing_right |
one bit is missing; result.need names it |
403 |
invalid_argument |
an argument is wrong — layer, content, identifier, a missing target, a cursor from another search | 400 |
invalid_target |
outside the typed file grip: root, extension, spelling, prefix | 400 |
not_found |
nothing at this path, layer, kind or actor | 404 |
exists |
create on something that exists; add on an existing actor | 409 |
conflict |
state changed underneath: the draft changed during the audit, a draft blocks an unpublish, a lock, the index moved under a search cursor | 409 |
unsupported |
deliberately not through this door: assets via create, the project layer or organisation off live, a rename | 400 |
refused |
the scope check or the plan said no; result.failures[] per target |
422 (413 when it is size) |
audit_failed |
the scope audit is not clean; result.audit |
422 |
audit_unavailable |
the audit could not run — no interpreter (PHP_CLI), no transit folder (.tmp), no usable output, or a scope over SITE_AUDIT_MAX_BYTES (“scope too large”: a size, not a content error — nothing to fix in the draft; the site owner raises the cap) — on every path; the error names the cause; fail-closed |
503 |
transit_failed |
server-side: tmp, stage, zip or lock | 500 |
unknown_verb |
no verb by that name; result.verbs lists them |
400 |
Over MCP the envelope travels twice: as content[0].text for the agent and as structuredContent for a client, which can validate it against the tool’s outputSchema from tools/list — the envelope above plus, per verb, the result keys every success carries. isError mirrors ok. The core’s suite (suite/) runs every MCP call through that validator, so the shape is a regression floor, not a promise.
The audit behind the MCP
Publishing needs the right and a clean audit run; if the lint could not run, nothing goes live. A targeted publish is judged against live ∪ the targets: a foreign staged draft neither blocks nor rescues it, and a target leaning on one is refused — the message names it, and the fix is to publish them together. An unpublish is judged against live ∖ the targets and blocks when what remains would break. validate and a whole-round publish judge the full working copy. One layer verb at a time: publish, unpublish, discard and every stage hold the round, so a verdict and its act see the same site — two agents can’t each pass an audit that together breaks it; a round held past half a minute answers conflict (try again).
A staged project layer (config.php, functions.php, index.php) is more than linted: publish, unpublish and validate boot it — in the router’s order — inside a throwaway jail under .tmp/ (a copy of the engine and the scope’s theme PHP — a functions.php that requires its own lib/ boots whole — nothing else in reach, a time limit, an output cap); any staged theme PHP, or one leaving live, sets it off, since the layer may require it at load. Code that parses but dies at load is refused, and a staged config.php is judged as the scope it declares: a language still carried by live data cannot leave SITE_LOCALES, and SITE_LANG_DEFAULT and SITE_ORG never change through the MCP. Stage feedback (create, update, pack) judges without booting. The boundary, honestly: theme.write is a trust capability — the theme is executable PHP: once published it runs as the site, and staged it already runs in a draft preview, for whoever opens the preview link. The smoke catches mistakes, not intent; the lint is not security.
The plan envelope
Optional: .plan/offer.json, a Schema.org Offer with a limits block — storageMB across the four roots (live and staged), items (data entities, live and staged — the stage is the enforcement point), actors (files in .actors/, counted when a key is added through the MCP). No file, no limits; a missing key, unlimited; an unreadable file, no plan (the plan verb reports it). Checked on every MCP write after the scope check; over-limit blocks new writes and erases nothing. Read-only through the MCP — changing it is an owner act; the catalogue of plans lives with whoever offers them. See Plans and limits.