# Garchi CMS for AI agents

Garchi CMS is a hosted headless CMS. It stores structured content — pages, sections,
blog posts, products, images — and serves it over an API. Your application renders it.

The idea that matters: **content lives in Garchi, code lives in the repository.** The
integration is written once. After that, copy, images, pages and articles change in
Garchi without another code change. New copy or a new article is never a reason to
edit source files.

Work through the steps below in order. Step 1 gates everything after it.

---

## Step 1 — Connect the Garchi MCP server

**If you cannot reach Garchi over MCP, you cannot complete this task.** Scaffolding a
project or installing skills without it produces an application with no content behind
it — components with nothing to render, and a user who has to wire up the CMS by hand
anyway. Do not proceed to any later step until a Garchi read call has succeeded.

Two things not to do when you are blocked here. **Do not invent, request or guess a
token to work around it** — there is no key that makes MCP work, and asking for one
sends the user looking for something that does not exist. **Do not write content into
source files as a substitute for CMS access.** An application with the copy hardcoded
into its components is not the task: it looks finished, it hides the failure from the
user, and every later content change still has to go through a developer. Report the
blocker instead and let the user clear it.

```
https://garchi.co.uk/mcp-oauth
```

Streamable HTTP. OAuth 2.1 with PKCE and dynamic client registration — the client
registers itself and the user approves in a browser.

**Already connected?** If Garchi tools are already available to you, the server is set
up — run the verification below and go straight to step 2. Do not add it again, and do
not ask the user to.

Otherwise pick the case that matches you.

### Case A — you can run shell commands

Claude Code, VS Code, Cursor, Codex and similar. Add the server yourself.

**Claude Code:**

```bash
claude mcp add --transport http garchi https://garchi.co.uk/mcp-oauth
```

Then run `/mcp` in the session and complete the browser login.

**VS Code** — no add command; write `.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "garchi": {
      "type": "http",
      "url": "https://garchi.co.uk/mcp-oauth"
    }
  }
}
```

VS Code must (re)start the server before its tools appear. Tell the user to run
**MCP: List Servers** from the Command Palette and start `garchi`, or to reload the
window.

**Cursor** — write `.cursor/mcp.json` in the project (or `~/.cursor/mcp.json` for
every project):

```json
{
  "mcpServers": {
    "garchi": {
      "url": "https://garchi.co.uk/mcp-oauth"
    }
  }
}
```

Cursor prompts for OAuth once it picks the server up. Tell the user to reload the
window if it does not.

**Any other client that reads `.mcp.json`:**

```json
{
  "mcpServers": {
    "garchi": {
      "type": "http",
      "url": "https://garchi.co.uk/mcp-oauth"
    }
  }
}
```

Write the file, then tell the user to reload their client. Editing config alone never
loads the tools into a running session.

### Case B — you cannot run shell commands

claude.ai on web or mobile, ChatGPT, and other hosted chat clients. **You cannot
install anything. Do not try, and do not carry on without it.** Give the user the
exact path, then stop and wait for them.

On claude.ai (web): **Customize → Connectors**, click **"+"**, choose **Add custom
connector**, paste `https://garchi.co.uk/mcp-oauth`, click **Add**, then approve the
sign-in. In Claude Desktop the same page sits under **Settings → Connectors**.

On ChatGPT (web; Pro, Plus, Business, Enterprise or Edu): if **Garchi CMS** appears in
the app directory, connect it there and approve the sign-in. If it does not, the user
adds it manually: **Settings → Security and login → Developer mode**, then open
**Plugins**, click **+**, and enter `https://garchi.co.uk/mcp-oauth` as the MCP server
URL. Developer mode is required for any server that is not in the directory — without
it there is no way to add one, so do not send the user hunting through the directory.

Other clients: add a custom or remote MCP connector with that URL and approve the
sign-in.

Then wait. Do not start work until the user confirms and a read call succeeds.

### Verify before continuing

Call the Garchi tool that lists spaces. Match the outcome:

| What happens | What it means | What to do |
| --- | --- | --- |
| The call returns spaces | Connected | Continue to step 2 |
| The call fails on authentication | The server is configured but OAuth is not approved | Tell the user to approve the Garchi sign-in in their browser, then wait and call again |
| No Garchi tools exist at all | The client has not loaded the server yet | Tell the user to reload or restart their client. **Stop here** — retrying the call cannot fix this, and neither can editing the config again |

The third row is the one that wastes sessions. A missing tool is not a failed call;
there is nothing to retry, and no amount of re-reading config changes it. Say plainly
that the client needs a restart and stop.

**A space must also exist.** A space is the content workspace and everything is scoped
to it. The user creates it at https://garchi.co.uk/dashboard — nothing over MCP creates
one. If the space list comes back empty, ask for one before going further.

---

## Step 2 — Install the Garchi skills

**Required before any content or integration work.** The skills carry the field rules,
the safe order of operations and the rendering patterns that the rest of the job
depends on, and they are updated as the product changes. This page is deliberately
short; the skills are the detail.

```bash
npx skills add lumenharbor/garchi-cms-skills
```

Installs into the project by default; add `--global` to install for every project, and
`--all` to skip the prompts. Three skills arrive: planning a project, writing the
rendering code, and running content operations.

The CLI covers Claude Code, Cursor, Codex, Cline, Copilot, Windsurf, OpenCode and most
other file-based agents. It cannot install into hosted chat clients with no filesystem
— on those, read the skills directly from
https://github.com/lumenharbor/garchi-cms-skills instead.

**Verify:** confirm the three `garchi-*` skills are present. Some clients only load
skills at session start, so if they are on disk but not available to you, say so and
ask the user to start a new session rather than continuing without them.

---

## Step 3 — Decide what kind of job this is

| Situation | Do this |
| --- | --- |
| Empty folder — Next.js, Nuxt or Laravel | Scaffold an official starter kit, then model the content |
| Empty folder — any other framework | Integrate the SDK or REST API by hand — see **Rendering the content in an application** below — then model the content |
| Existing application | Integrate into the existing project — see **Rendering the content in an application** below. **Never** scaffold a starter kit over a working app |
| "Change the copy / add a post / new landing page" | Content operations only. Do not touch application code |

**"Empty folder" means empty:** no `package.json`, no `composer.json`, and no source
directory. A repo holding only a README and a licence still counts as empty; anything
with dependencies or source code does not, however small.

Say which branch you took and why before writing any file.

---

## Step 4 — Starter kits (new projects only)

Three maintained scaffolds. Each ships the SDK, a server-side Garchi client, a
`getPage(slug, mode)` helper, a section renderer and example section components.

```bash
npx @lumenharbor/garchi-starter-kit -k next -n my-project
```

`-k` accepts `next`, `nuxt` or `laravel`. `-n` sets the target directory.

| Kit | Repository | SDK |
| --- | --- | --- |
| Next.js | github.com/lumenharbor/garchi-next-starter-kit | `@garchicms/garchi-node-sdk` |
| Nuxt | github.com/lumenharbor/garchi-nuxt-starter-kit | `@garchicms/garchi-node-sdk` |
| Laravel | github.com/lumenharbor/garchi-laravel-starter-kit | `garchicms/garchi-sdk-php` |

The CLI may advertise other kit names. Only these three are maintained.

Use a kit only when the directory is empty, the framework is one of the three, and
there are no existing conventions to preserve. For anything else — an existing app of
any size, SvelteKit, Astro, Django, Rails, React Native — integrate the Node SDK, the
PHP SDK or the REST API instead, and read a kit as a reference if useful.

---

## Rendering the content in an application

Managing content needs nothing installed locally. Rendering is separate work, and the
shape is the same in every framework: one server-side Garchi client built from the API
key and never reaching the browser; a `getPage(slug, mode)` helper (`live` in production,
`draft` behind a preview token); a renderer that resolves each section to a component by
the section template's `description`, falling back to `name`; section components that
forward unknown props to their root element so the Garchi visual editor keeps working;
and HTML sanitisation before rendering rich text.

Node SDK `@garchicms/garchi-node-sdk`, PHP SDK `garchicms/garchi-sdk-php`, or the REST
API for anything else. The rendering skill from step 2 has the patterns and the code.

---

## Credentials

Two separate things. They are not interchangeable, and mixing them up is the most
common setup mistake.

| | MCP connection | Application API key |
| --- | --- | --- |
| Used for | An agent reading and writing content | The app fetching content at runtime |
| Auth | OAuth — user approves in their client | An account API key |
| Ask the user for it? | **Never.** No API key is involved in connecting to MCP; if you are looking for a token to make MCP work, you are on the wrong path | **Yes, when wiring up rendering** |
| Lives in | The client's own token store | A server-side environment file |

Asking the user for the application API key is correct and expected — the app cannot
read content without one, and only the user can produce it. Ask for:

- **API key** — dashboard → Settings → API Keys. It belongs to the **account**, not to a
  space, and covers every space the account owns (up to five keys per account). The
  user may already have one.
- **Space UID** — shown on the space in the dashboard. This is what scopes a request to
  one space, not the key.
- **Preview token** — Space Settings. This one **is per space**. Only needed to render
  unpublished drafts.

The starter kits read `GARCHI_API_URL` (`https://garchi.co.uk/api/v2`), `GARCHI_API_KEY`,
`GARCHI_SPACE_UID` and `GARCHI_PREVIEW_TOKEN` — from `.env.local` (Next), `.env`
(Laravel), or top-level `runtimeConfig` in `nuxt.config.ts` (Nuxt, where top level keeps
them server-only).

Write the keys into the environment file as empty placeholders yourself, then tell the
user which lines to fill in. If the user gives you a value directly, write it into the
server-side environment file and nowhere else.

Non-negotiable, whichever way the value arrives:

- Server-side only. Never behind a browser-exposed prefix (`NEXT_PUBLIC_`, `VITE_`,
  `PUBLIC_`), never in client bundles, never in a component that ships to the browser.
- Never committed. Check the environment file is git-ignored before writing to it.
- Never repeated back into chat, a log, a screenshot, a commit message, a generated
  file or a documentation example.
- Never used to authenticate MCP, and an MCP session is never a source for it.

---

## The content model, in brief

Enough to plan with. The skills carry the field rules, prop types, tool order and code
patterns — read them rather than guessing from this summary.

**Space.** The container, identified by a `space_uid`. Owns everything below. Listing
spaces returns the uid, per-type content counts and the space's front-end URL, which is
enough to tell which space the user means and what already exists. A user may own
several; ask if it is ambiguous.

**Two content systems, chosen by intent.** They do not share media.

| System | Use for | Built from | Images |
| --- | --- | --- | --- |
| **Pages** | One-off designed pages: home, about, pricing, landing pages | Section templates → sections → props | Space **assets**, referenced by id |
| **Data items** | Collections of similar records: articles, products, documents | Data item → categories → metadata | Inline base64 on the item |

A section template is the reusable blueprint for a type of section, and its
`description` is the **frontend component path** (e.g. `components/garchi/HeroContainer`)
— that string is the wire between CMS content and a real component in the codebase. A
page is a shell plus an ordered list of sections. A data item is one record — article,
product, document — belonging to at least one category.

**Every write leaves a draft.** This is the rule that most changes how you report work,
so it has its own section below.

---

## Publishing: you write drafts, the user publishes

Nothing an agent writes reaches the live site by itself. This is deliberate — it gives
the user a review step before their visitors see the change.

- **Pages.** Every content write puts the page into draft. `mode=live` keeps serving the
  last published version, so the site never breaks mid-edit.
- **Data items.** New and updated items are drafts, and the content API serves published
  items only. `scheduled_for_datetime` is the one exception: it publishes the item
  automatically at the time you set.

No tool publishes anything. **Finish every content task by naming the pages and items you
changed and telling the user to publish them in the Garchi dashboard.** Leaving that out
is how a user ends up believing a change is live when it is not — and reading the content
back over MCP will not reveal the problem, because reads show drafts.

---

## Rules that prevent almost every failure

1. **Orient before writing.** List spaces first. One call tells you which space, what is
   in it, and what its front end is.
2. **Read before you edit.** Fetch the current draft or item and work from real ids and
   real current values.
3. **Verify after you write.** A success message confirms the call ran, not that the
   result is what the user wanted. Read it back.
4. **Never guess an id.** Almost every call takes an id a previous call returned. Nothing
   is derivable. If you do not have it, list for it.
5. **Do not re-list what you already have.** Template, asset and category lists are
   stable within a task — fetch once, reuse.
6. **Send only what changes.** Omitted fields are untouched; a field sent as `null` or an
   empty string is emptied. Never re-send a whole record to change one field, and never
   pad a request with nulls for arguments you are not setting. Fields a record cannot
   live without — a data item's `name`, `slug`, `detail_description` and `categories`, a
   page's `title`, `description` and `path` — refuse an empty value rather than wiping
   the record.
7. **Leave notes.** Spaces, pages, templates, items and assets all accept an
   `agent_description`. Fill it in when you create something — it is what the next
   session reads instead of guessing.
8. **Stop conditions.** Never retry a failing call more than twice. A validation error
   names the exact field and rule; fix that field rather than resending. A limit or
   subscription message is a billing state, not a transient failure — stop, and report
   which limit was hit and what was created before it. Plan allowances:
   https://garchi.co.uk/pricing

### Before anything hard to undo

Deleting a section removes it, every nested section under it, and all their prop values.
Changing a prop's key or type on a template affects every section using that template
across every page and breaks the matching component prop in the codebase. For either:
read first, name the exact target, get an explicit yes, and confirm one item at a time.
"Tidy up this page" is not approval to delete anything. The dashboard keeps automatic
restore points for recent page, section-template and data item changes, so tell the user
to look there before calling something lost — but the window is limited and **nothing
over MCP restores anything**, so from your side these changes are final.

---

## Not available over MCP

Tell the user to do these in the dashboard rather than looking for a tool:

- **Creating a space.**
- **Publishing a page or a data item.** See the publishing rule above.
- **Deleting pages, data items, categories or section templates.** Removing a section is
  the only delete available.
- **Creating API keys.**

---

## Before you report the task finished

- [ ] The Garchi MCP server is connected and a read call succeeded. If it is not, say so
      first — whatever else you built is not wired to a CMS.
- [ ] The Garchi skills are installed.
- [ ] Every page and item you created or changed is named, with a note that the user
      needs to publish it in the dashboard.
- [ ] Any credential the user still has to fill in is named, with the exact file and line.

---

## Reference

- Documentation — https://garchi.co.uk/documentation
- MCP client setup — https://garchi.co.uk/mcp-docs
- REST API — https://garchi.co.uk/docs/v2 · OpenAPI — https://garchi.co.uk/docs/v2.openapi
- Skills and starter kits — https://github.com/lumenharbor/garchi-cms-skills
- Plans and limits — https://garchi.co.uk/pricing
- Support — https://garchi.co.uk/contact_us

This page covers connecting and orienting only. **The installed skills are canonical for
field rules, prop types, tool sequences and code patterns** — where this page and a skill
disagree, follow the skill, then the server's own guide, then the documentation.