---
name: contentful-cms-setup
description: "Guide a user through connecting hosted cms-edit MCP for Claude or Grok (OAuth)."
---

# Skill: cms-edit Setup

Use this skill when the user wants to connect Claude or Grok to their Contentful site via **hosted cms-edit MCP**.

Local stdio MCP and the setup wizard are **not supported**. Editors connect through the site's `/cms-edit` onboarding flow.

---

## Hosted setup (Claude Integrations + OAuth)

Use when SE sent an **onboarding link** (e.g. `https://your-site.content.se.studio/cms-edit`).

### Step 1: Connect to Claude

1. Open the link SE sent (or **Connect to Claude** on `/cms-edit`)
2. Confirm the connector in Claude Desktop or claude.ai
3. Sign in with **Contentful** when prompted (same account SE invited to the space)

Manual alternative: Claude → **Customize → Connectors** → Add custom connector → paste the MCP URL (`…/api/mcp`) → Connect.

Full editor guide: `packages/contentful-cms/HOSTED.md`

### Step 2: Verify

In Claude, ask to read the cms-edit guide and **tasks-index**, then verify the connection. If `cms_edit` returns content, setup is complete.

Use skill **`contentful-cms-editor-tasks`** for the tasks-index → capability playbook workflow.

**Reconnect:** Settings → Integrations → Connect again if the connection stops working.

---

## Hosted setup (Grok Build)

Use when the user wants cms-edit in **Grok Build** (not local stdio MCP).

### Step 1: Configure Grok

Add to `~/.grok/config.toml`:

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

The URL **must** end with `/api/mcp`. Use the MCP URL from the site's `/cms-edit` page.

### Step 2: Connect

1. In Grok, run `/mcps`
2. Select the cms-edit server
3. Press **`i`** to initiate OAuth (not just enable)
4. Sign in with Contentful when prompted

### Step 3: Verify

Run `grok mcp doctor cms-edit-<projectKey>` or call `cms_edit_version` in a Grok session.

**Reconnect:** `/mcps` → press `i` again if OAuth expires.

Full guide: `packages/contentful-cms/docs/mcp/hosted-guide.md` (Grok Build section).

---

## Developers (CLI + skills, not local MCP)

For engineering work in a site repo (Cursor, Grok, terminal):

1. Configure `.contentful-cms.json` in the project (or `~/.contentful-cms.json`) with space credentials
2. Run `npx skills add @se-studio/skills` or `pnpm skills:sync` in the monorepo
3. Bundled cms-edit skills (`core`, `setup`, etc.) are included when you run `npx skills add @se-studio/skills`
4. Read `cms-edit/<site>/editor-pack/tasks-index.md` before editing content

Do **not** register a local `mcpServers.cms-edit` entry in Claude Desktop — use the hosted connector URL instead.

---

## Troubleshooting

**OAuth / sign-in fails**
→ Confirm the user was invited to the Contentful space and is signing in with the correct account. In Grok, use `/mcps` → press `i` (not just toggle). Confirm config URL ends with `/api/mcp`.

**Grok browser flashes and closes**
→ Usually a redirect_uri mismatch before cms-edit v2.7.7+; upgrade the hosted deployment and retry OAuth.

**`cms_edit` tool not available**
→ Reconnect via `/cms-edit` or Claude Integrations. Remove any legacy local MCP or `.mcpb` extension entries.

**Connection works but wrong site**
→ Each connector URL is site-specific; use the URL from the project's `/cms-edit` page.

**Multiple cms-edit connectors enabled (Cowork)**
→ Hosted MCP tools are labeled per site: server name `cms-edit-<projectKey>`, descriptions `[Site Name cms-edit] …`. Say “use **Brightline** cms-edit” and match that label. Verify with `cms_edit_version` → `projectKey`. Disable other cms-edit connectors for single-site work.