---
title: "MCP Server Tools"
description: "Complete catalogue of ComStack MCP tools with role requirements, annotations, and descriptions. Grouped by function from state reads to publishing."
url: "https://comstack.ai/docs/mcp/tools/"
---
## What this is

The complete catalogue of tools the ComStack MCP Server exposes to AI assistants. Tool availability is filtered per caller role — a viewer won't see manager-only tools, and those tools won't appear in `tools/list`.

## How it works

Each tool carries MCP `ToolAnnotations` that tell clients what kind of approval UI to show:

- **`readOnlyHint: true`** — read-only; clients can call without an approval prompt.
- **`destructiveHint: true`** — modifies state in a hard-to-reverse way; clients show an approval prompt with arguments visible.
- **`destructiveHint: false` + `idempotentHint: false`** — additive write (e.g. `create-page`); safe to call but not idempotent.

Annotations are advisory — the server enforces auth, role checks, `project_name` echo, and the confirmation-token flow regardless.

## When to use it

Consult this page to understand which tools are available for a given role, what annotations they carry, and what approval flow the client will use.

## Parameters / fields / inputs

The `Role` column shows the minimum role required.

### Identity and project access

| Tool | Role | Type | Description |
|---|---|---|---|
| `whoami` | any | read | Show signed-in identity. |
| `list-my-projects` | any | read | List accessible projects with your role on each. |
| `create-project` | any | write | Create a new project from a project template. |
| `get-guide` | any | read | Agent guide, metadata schema, Lighthouse checklist. |
| `report-feedback` | any | write | File a bug or improvement suggestion. |

### Project state

| Tool | Role | Type | Description |
|---|---|---|---|
| `get-project-state` | viewer | read | Full snapshot: pages by status, templates, locales, translation mode, `next_action` per page. |
| `get-page-content` | viewer | read | Fetch one page including status, audience, and `next_action`. |
| `list-pages` | viewer | read | Filter pages by status, audience, template, or language. |
| `search-docs` | viewer | read | Ranked keyword search across pages. |
| `list-project-doc-templates` | viewer | read | Page templates available in this project. |

### Page editing

| Tool | Role | Type | Description |
|---|---|---|---|
| `create-page` | editor | write | Create a new draft page. Validates all fields at once and rejects path and slug collisions. |
| `update-page` | editor | destructive | Edit an existing page. Live pages become a new draft; the live URL stays up until publish. |

### Approvals and translation

| Tool | Role | Type | Description |
|---|---|---|---|
| `approve-page` | manager | idempotent | Approve a draft. Full validation runs; translations start automatically. Page moves to ready when all locale variants land. |
| `translate-page` | manager | idempotent | Retry the platform translation fan-out for an approved or ready page. |
| `submit-page-translation` | editor | idempotent | Supply one locale's translation for an approved source page (client translation mode). |

### Publishing

| Tool | Role | Type | Description |
|---|---|---|---|
| `publish` | manager | read | Dry run: build the manifest of due READY pages with per-page diff and a confirmation token (5-min TTL). |
| `publish-confirm` | manager | destructive | Deploy: use the token to promote ready pages to live. Async — poll `publish-status` for results. |
| `publish-status` | viewer | read | Poll async publish progress; returns `published_urls` when complete. |
| `list-publish-history` | viewer | read | Recent publishes with revert window. |
| `revert-publish` | manager | destructive | Roll back the last publish within 1 hour. Requires `project_name`. |

### Page management

| Tool | Role | Type | Description |
|---|---|---|---|
| `delete-page` | manager | destructive | Hard delete (no undo). Requires `project_name`. |
| `set-page-status` | manager | destructive | Archive, restore, or revert a page. Requires `project_name`. |
| `set-page-audience` | manager | destructive | Set who can see a page: `public`, `agents`, `members`, or `internal`. Applied to the whole canonical slug group. Requires `project_name`. |

### Site configuration

| Tool | Role | Type | Description |
|---|---|---|---|
| `update-theme` | manager | destructive | Set colours, fonts, and CSS for the knowledge site. |
| `update-design` | manager | destructive | Theme the live site and custom pages (accent set, palette, fonts, colour scheme). |
| `update-website-settings` | manager | destructive | Set the published website country list and toggle the module. Requires `project_name`. |
| `update-advanced-settings` | manager | destructive | Update advanced project settings including translation mode. |
| `update-live-agent-settings` | manager | destructive | Configure live voice agent settings. |
| `update-legal-settings` | manager | destructive | Update legal and compliance settings. |
| `update-chrome-ingest-settings` | manager | destructive | Configure Chrome Extension ingest settings. |
| `update-custom-pages-settings` | manager | destructive | Configure the custom pages module settings. |

### GitHub sync

| Tool | Role | Type | Description |
|---|---|---|---|
| `connect-github` | manager | destructive | Save repo, branch, and docs folder. Requires `project_name`. |
| `pull-and-publish` | manager | destructive | Full-replace sync from GitHub. Requires `confirm: "REPLACE_ALL_DOCS"` and `project_name`. |
| `get-github-config` | member | read | Current GitHub connection state. |
| `update-github-sync` | manager | destructive | Update GitHub sync settings. |

### Navigation

| Tool | Role | Type | Description |
|---|---|---|---|
| `list-sidebar-groups` | member | read | List the project's sidebar groups. |
| `get-sidebar-group` | member | read | Fetch one sidebar group. |
| `create-sidebar-group` | manager | write | Create a new sidebar group. Requires `project_name`. |
| `update-sidebar-group` | manager | destructive | Edit a group's label, order, icon, or visibility. Requires `project_name`. |
| `delete-sidebar-group` | manager | destructive | Delete a group. Requires `project_name`. Fails if pages reference it. |
| `reorder-sidebar-groups` | manager | destructive | Replace the full sidebar group ordering. Requires `project_name`. |
| `reorder-pages-in-group` | manager | destructive | Bulk-set page order inside a group. Requires `project_name`. |
| `list-header-nav-items` | member | read | List top-nav items sorted by order. |
| `create-header-nav-item` | manager | write | Create a top-nav item. Max 10 per project. Requires `project_name`. |
| `update-header-nav-item` | manager | destructive | Edit a top-nav item's label, URL, icon, or visibility. Requires `project_name`. |
| `delete-header-nav-item` | manager | destructive | Delete a top-nav item. Requires `project_name`. |
| `reorder-header-nav-items` | manager | destructive | Replace the full top-nav ordering. Requires `project_name`. |

### Custom pages and media

| Tool | Role | Type | Description |
|---|---|---|---|
| `upload-custom-page` | editor | destructive | Upload a custom (vibe-coded) page. Replaces the full `body_source`. Extracts translatable strings. |
| `upload-media` | editor | write | Upload an image or video; returns an optimised delivery URL. |

### Account and usage

| Tool | Role | Type | Description |
|---|---|---|---|
| `get-usage-report` | any | read | Account usage totals and per-module breakdown. |
| `get-credit-balance` | any | read | Available credits, balance, reserved, frozen flag. |
| `list-api-keys` | any | read | API keys on the project. |
| `generate-api-key` | manager | write | Generate a new API key. |
| `revoke-api-key` | manager | destructive | Revoke an API key. |
| `repair-translations` | manager | destructive | Backfill missing locale siblings. Requires `project_name`. Dry-run mode available. |
| `lookup-company` | any | read | Look up a company. External-facing — open world. |

### Page templates (admin)

| Tool | Role | Type | Description |
|---|---|---|---|
| `list-doc-templates` | any | read | All page templates on the platform. |
| `get-doc-template` | any | read | Field schema, metadata example, markdown template, and slug examples. |
| `create-doc-template` | admin | write | Create a new page template. |
| `update-doc-template` | admin | destructive | Update an existing page template. |
| `delete-doc-template` | admin | destructive | Soft-delete a page template. |
| `list-project-templates` | admin | read | Project templates on the platform. |
| `get-project-template` | admin | read | Fetch one project template. |
| `create-project-template` | admin | write | Create a new project template. |
| `update-project-template` | admin | destructive | Update a project template. |
| `delete-project-template` | admin | destructive | Soft-delete a project template. |
| `assign-project-template` | admin | destructive | Add a page template to a project's available templates. |
| `unassign-project-template` | admin | destructive | Remove a page template from a project. |

### Flows and steps

| Tool | Role | Type | Description |
|---|---|---|---|
| `list-flows` | viewer | read | List all flows in a project. |
| `get-flow` | viewer | read | Fetch one flow. |
| `create-flow` | editor | write | Create a new flow. |
| `update-flow` | editor | destructive | Update a flow. |
| `delete-flow` | manager | destructive | Delete a flow. |
| `list-steps` | viewer | read | List steps in a flow. |
| `get-step` | viewer | read | Fetch one step. |
| `add-step` | editor | write | Add a step to a flow. |
| `update-step` | editor | destructive | Update a step. |
| `remove-step` | manager | destructive | Remove a step. |
| `list-step-types` | viewer | read | Available step types. |

## Example

Checking what tools are available for your role:

Call `get-project-state` — the `next_action` on each page row tells you the next step and whether your role can perform it (`next_action_allowed` and `next_action_min_role`). The `tools/list` response is pre-filtered for your role, so any tool absent from the list is beyond your current role on this project.

## Common errors

| Error | Cause | Fix |
|---|---|---|
| Tool absent from `tools/list` | Below required role for that tool | Use a higher-role account or ask a manager |
| `403 project_name mismatch` | `project_name` doesn't match stored name | Call `get-project-state` first |
| Validation error on write | Missing required template fields | The error response lists all issues at once with fix strings |

## Related

- [MCP Server overview](/docs/mcp.md) — transport, routing, and rate limits
- [Install](/docs/mcp/install.md) — connect an AI assistant
- [Examples](/docs/mcp/examples.md) — end-to-end workflow examples