---
title: "MCP Examples"
description: "End-to-end examples showing how an AI assistant reads project state, edits pages, approves, and publishes using ComStack MCP tools."
url: "https://comstack.ai/docs/mcp/examples/"
---
## What this is

End-to-end examples showing how an AI assistant uses ComStack MCP tools — from reading project state through editing, approving, and publishing. Each example shows the user prompt, the tools called, and the expected outcome.

## How it works

The assistant follows the page lifecycle: read state → draft edit → approve (translations run automatically) → publish dry run → publish confirm. All tool calls pass `project_id`; destructive calls also pass `project_name` (always call `get-project-state` first to get the correct value).

## When to use it

Use these examples as a reference when building integrations, writing instructions for an AI assistant, or understanding the tool call sequence for a given workflow.

## Parameters / fields / inputs

Key arguments used across examples:

| Argument | Where used | Notes |
|---|---|---|
| `project_id` | All tools | Required on every project-scoped tool call |
| `project_name` | Destructive tools | Must exactly match the stored project name |
| `path` | Page-level tools | The Firestore doc id — use slug when you only have a URL |
| `confirmation_token` | `publish-confirm` | Single-use, 5-min TTL — call `publish` again if it expires |

## Example

### Example 1 — Read: "Show me my drafts"

**User:** "What drafts do I have in my ComStack project?"

**Tools called:**

1. `list-my-projects` → `[{ project_id: "p8C98...", name: "Acme Real Estate", role: "manager" }]`
2. `get-project-state` with `project_id: "p8C98..."` → snapshot with `draft_pages: [{ path: "guides/buying", title: "Buying Guide" }, { path: "guides/selling", title: "Selling Guide" }]`

**Assistant response:** "You have 2 drafts: 'Buying Guide' and 'Selling Guide'. Would you like to edit or publish them?"

---

### Example 2 — Edit: "Update the homepage description"

**User:** "Change the homepage description to 'Find your dream property on the Costa del Sol'."

**Tools called:**

1. `get-project-state` → confirms project and gets `project_name: "Acme Real Estate"`
2. `get-page-content` with `slug: "index"` → current metadata and content
3. `update-page` with `slug: "index"`, `metadata: { description: "Find your dream property on the Costa del Sol" }` → `{ action: "draft_created_from_live", draft_id: "AbC...", next_step: "Present updated content to user for review" }`

**Assistant (presents the draft for user review):** "Here's the updated description. The live page stays up until we publish. Say 'approve' when ready — or let me know if you'd like to tweak the wording."

---

### Example 3 — Approve and publish: "Take it live"

**User:** "Looks good — take it live."

**Tools called:**

1. `approve-page` with the draft path → `{ status: "approved", next_action: "translating", locales_total: 2 }`. Translations run in the background; the assistant informs the user they can keep working.
2. *(later, after translations complete)* `get-project-state` → page is in `ready_pages` with `next_action: "publish"`.
3. `publish` with `project_name: "Acme Real Estate"` → manifest with the 3 ready pages (EN source + 2 translated variants) + `confirmation_token`.
4. **Assistant presents the manifest** (titles, URLs, byte sizes before/after) to the user.
5. `publish-confirm` with `confirmation_token` → `{ status: "running" }`. Deploy is async.
6. `publish-status` (poll until `succeeded`) → `published_urls`.

**Assistant response:** "Published! The pages are live at the URLs in the manifest. Here are the links: [lists published_urls]."

---

### Example 4 — Create a new page

**User:** "Create a new guide page about buying property in Marbella."

**Tools called:**

1. `get-project-state` → gets available templates and confirms no slug collision
2. `get-doc-template` with the relevant template id → receives `metadata_example`, `markdown_template`, and `quick_checklist`
3. `create-page` with the composed content and metadata → validates everything at once. If validation fails, the response lists all issues with fix strings in one go.

**Assistant (presents the new draft):** "Here's the draft 'Buying in Marbella'. Let me know if you'd like any changes before we approve and publish."

## Common errors

| Error | Cause | Fix |
|---|---|---|
| Token expired at step 5 | More than 5 minutes elapsed since `publish` | Call `publish` again for a fresh token |
| Manifest changed at `publish-confirm` | A ready page changed between dry run and confirm | Call `publish` again |
| `approve-page` refuses | Draft has validation errors | The response lists all issues; fix them and retry |
| Slug collision on `create-page` | Another page already uses that slug + language | Use `update-page` with the existing page's path, or choose a different slug |

## Related

- [MCP Server overview](/docs/mcp.md) — setup and transport
- [Install](/docs/mcp/install.md) — connect an AI assistant
- [Tools](/docs/mcp/tools.md) — full tool catalogue
- [Resources](/docs/mcp/resources.md) — reference materials for AI assistants