# Hosted cms-edit for Claude Desktop and Grok Build

Use this guide when your team hosts cms-edit on Vercel (one deployment per client). **You do not need Node.js, tokens, or config files** — only an MCP client (Claude Desktop or Grok Build) and a Contentful account.

Edits you make appear in Contentful under **your name**, because you sign in with your own Contentful account.

---

## What SE sends you

1. A link to your site's setup page (e.g. `https://dev.content.se.studio/cms-edit`)
2. This guide

You do **not** need to edit JSON, install Node.js, create API tokens, or configure connector URLs yourself.

---

## Before you start (SE team)

For each editor:

1. Invite them to the Contentful space.
2. Assign the **AI Editor** role (draft edit only — no publish). See [README — Contentful Role Setup](./README.md#contentful-role-setup-required).
3. Deploy `apps/cms-edit-host` to Vercel for this client (see [cms-edit-host README](../../apps/cms-edit-host/README.md)).
4. Send them the setup page URL and this guide.

---

## Step 1 — Install Claude Desktop

Install [Claude Desktop](https://claude.ai/download) if you have not already.

---

## Step 2 — Connect to Claude

**Easiest:** Open the link SE sent you (e.g. `https://dev.content.se.studio/connect` or **Connect to Claude** on `/cms-edit`). This opens Claude with the connector name and URL prefilled — confirm, then sign in with Contentful.

**Manual:** Claude Desktop → **Customize → Connectors** → **Add custom connector** → paste the MCP URL (e.g. `https://dev.content.se.studio/api/mcp`) → **Connect** → sign in with Contentful.

No extension install, no personal access token, no command line.

---

## Grok Build

Add the hosted MCP URL to `~/.grok/config.toml` (URL must end with `/api/mcp`):

```toml
[mcp_servers.cms-edit-<projectKey>]
url = "https://<your-host>/api/mcp"
enabled = true
```

In Grok: `/mcps` → select the server → press **`i`** to start OAuth → sign in with Contentful.

Verify: `grok mcp doctor cms-edit-<projectKey>` or call the `cms_edit_version` tool in a session.

See [hosted-guide.md](./docs/mcp/hosted-guide.md) for troubleshooting.

---

## Step 3 — Try it

**Getting started:** Ask Claude to read the **cms-edit guide** (`cms-edit://guide` resource) or use the **`cms_edit_verify`** prompt to check version and connectivity.

In a new Claude conversation:

> Read the cms-edit guide and verify the connection.

or:

> Open the homepage and show me the content tree.

If Claude returns JSON with page content or a snapshot with `@c0`, `@c1` refs, you are connected.

**Homepage slug:** On SE Studio sites, Contentful stores the homepage as slug `index` (public URL `/`). Use `open --page-slug /` or `open --page-slug /index` — both work. Site-specific exceptions are in `cms-edit://customer/routing`.

**Typical edit workflow:** `open --page-slug /` → `snapshot` → `read @c1` → `set @c1 heading "New title"` → `diff` → `save`.

Remember: **save creates drafts only**. You or a colleague must **publish in Contentful** for changes to go live.

**Do not pass `--space`** when using the hosted integration. The deployment is already configured for your site.

### What to ask Claude

Use natural language or these MCP prompts (slash commands / prompt picker in Claude):

| I want to… | Prompt or example |
|------------|-------------------|
| Check the connection | `cms_edit_verify` or “Read the cms-edit guide and verify the connection” |
| Explore the site | `cms_edit_explore` or “Show me the homepage content tree” |
| Fix copy on a page | `cms_edit_edit_page` or “Update the heading on /pricing” |
| Fix copy on an article | `cms_edit_edit_article` or “Update the article at /resources/blog/my-post” |
| Create a new page | `cms_edit_create_page` |
| Create a new article | `cms_edit_create_article` (every article needs an **article type**) |
| Turn a document into a page | `cms_edit_create_from_doc` |
| Turn a document into an article | `cms_edit_create_article_from_doc` |
| Go live | **Publish the draft in Contentful** — cms-edit never publishes |

**Claude drafts, Contentful publishes.** Use Contentful UI only to publish approved drafts and upload images — not to edit copy.

---

## Multiple cms-edit connectors (Cowork / Claude Desktop)

If you connect more than one hosted cms-edit site (Brightline, SE Studio, Pedestal, etc.), each connector exposes **site-specific** MCP metadata:

| Signal | Example (Brightline) |
|--------|----------------------|
| MCP server name | `cms-edit-brightline` |
| Tool descriptions | `[Brightline cms-edit] …` |
| `cms_edit_version` | `projectKey`, `displayName`, `spaceId` in JSON |

**Routing:** When you say “use the **Brightline** cms-edit”, the agent should pick tools whose name or description includes **Brightline** or `cms-edit-brightline` — not probe every `mcp__<uuid>` connector.

**One-shot verify:** Call `cms_edit_version` on the chosen connector and confirm `projectKey` is `brightline` (and `spaceId` is `96gdpqkm7elu` for Brightline).

**Single-site tasks:** Disable other cms-edit connectors in Integrations when you only need one site (e.g. blog tag matrix export).

---

## Troubleshooting

| Problem | What to do |
|---------|------------|
| **Connection stopped working** | Open Settings → Integrations and click **Connect** again to refresh your Contentful sign-in. |
| **Wrong site / agent probes all connectors** | Use site name in your request; check `cms_edit_version` → `projectKey`. Disable unused cms-edit connectors. Start a new conversation after connector updates. |
| **No cms_edit tool in Claude** | Confirm the integration is connected under Settings → Integrations. |
| **No active session** (after `open` worked) | Do not pass `--space`. MCP uses session `_mcp` automatically. Run `["diagnose"]` to inspect state. |
| **Wrong space** | Your Contentful account must have access to this site's space. Ask SE if unsure. |
| **Check cms-edit version** | Ask Claude to use the `cms_edit_version` tool, or run `curl -s "https://YOUR-DEPLOYMENT.vercel.app/api/health" \| jq .cmsEdit`. |

### Health check

```bash
curl -s "https://YOUR-DEPLOYMENT.vercel.app/api/health"
```

All checks should show `"ok": true`. If `redis` or `oauth` is not ok, contact SE to fix the deployment.

---

## Legacy: `.mcpb` extension (deprecated)

Older deployments used a Claude Desktop **extension** (`.mcpb`) with a manual Contentful personal access token. New setups use **Integrations + OAuth** instead. If your extension stopped working, remove it (Settings → Extensions) and reconnect via your site's `/cms-edit` page.

---

## Developers

Local stdio MCP is not supported. Use the hosted connector URL from `/cms-edit`, or run `cms-edit` CLI in a repo with `.contentful-cms.json`. See [INSTALL.md](./INSTALL.md).