Your first successful edit

This recipe works through MCP tools or their matching /v1/<tool_name> API endpoints. It requires read and content scopes.

1. Understand the site

Call get_site_context with {}. Record its revision, available folders and permissions. Call get_capabilities to see supported fields and designs.

Call search_content with {"q":"Alumni milestones"} to avoid duplicates. If the collection or story already exists, update it instead.

2. Validate a small batch

Replace revision below with the live value. Generate a fresh key for this logical change. Each ref is local to this batch; $alumni refers to the folder created in the preceding operation.

{
  "revision": 1,
  "idempotencyKey": "alumni-milestones-001",
  "dryRun": true,
  "changes": [
    { "action": "create_folder", "ref": "alumni", "fields": { "name": "Alumni milestones" } },
    { "action": "create_entry", "ref": "welcome", "fields": {
      "folderId": "$alumni",
      "kind": "story",
      "title": "Every graduate has a story",
      "body": "A place to celebrate our alumni and the paths they take.",
      "status": "draft"
    } }
  ]
}

Send this to apply_changes. A successful dry run returns valid: true and does not write content, audit records or media. IDs from a dry run are not reserved.

3. Save the draft

Send the same request with dryRun: false. The response includes the new revision, changeCount and a created map containing actual IDs for alumni and welcome.

The batch saves once, atomically. If any change fails, none of the batch is saved. A new live edit between validation and saving returns revision-conflict; reread and reconcile rather than overwriting.

4. Preview

Call preview_site with {}. Open its previewUrl in your browser—no account login is required. It uses the real shared renderer, including private photos, for the exact saved revision. Inspect the homepage, a collection, and a profile at desktop and mobile sizes before publishing.

This is a secret, read-only link, not a public share URL. It expires after 10 minutes, when the draft changes, or when its connection is disconnected. Share only with the person reviewing the draft; keep it out of logs and public messages. Run preview_site again after edits or expiry. Reloading after the browser removes the secret from the address bar also requires a fresh link.

Tell the user what changed and provide the preview. Do not report the site as live: publishing is a separate step.

5. Publish only when requested

If the user asks to publish and the connection has permission, follow publishing and delivery. Otherwise the draft is ready for the site's publisher.

Reliable retries

If a save response is lost, resend the exact batch with the original revision and key. An accepted batch returns replayed: true; it is not created again. Changing a batch while reusing its key returns idempotency-conflict.