---
title: "Get started with the MCP server"
description: "Connect the MCP server to Claude, ChatGPT or Claude Code, then drive your first publish with copy-paste prompts and a safe test project."
url: "https://comstack.ai/docs/mcp/setup/"
---
## What this is

The human on-ramp: connect the MCP server to your assistant, confirm it works, and run your first publish from a few copy-paste prompts — ideally against a throwaway test project so nothing reaches a live site by accident.

## How it works

The server runs at `https://api.comstack.ai/mcp` over streamable HTTP. People connect with OAuth (a browser sign-in); machines use API-key headers. Once connected, the tools appear in your client, and every call is scoped by a `project_id` you pass explicitly.

## Connect your client

The quickest path for everyone is the **[Account page](https://account.comstack.ai/connectors)** — its Connectors tab has one-click setup for Claude (web/desktop/mobile), ChatGPT, the Chrome extension, and Claude Code, with copy-paste fields and a live connection indicator.

Manual setup, by client:

### Claude (web, desktop, mobile)

1. Open **Customize → Connectors → Add custom connector**.
2. Enter **Name** `ComStack` and **Server URL** `https://api.comstack.ai/mcp`.
3. Click **Connect** and sign in with Google when the popup opens.
4. The server appears in any new conversation — open the **+** menu, choose **Connectors**, and turn on **ComStack**.

### ChatGPT

ChatGPT connects to remote MCP servers through **Developer mode**, on paid plans (Plus, Pro, Business, Enterprise, or Edu — not Free).

1. In ChatGPT, open **Settings → Apps & Connectors** (sometimes labelled **Connectors**) → **Advanced settings**, and turn on **Developer mode**. On Business, Enterprise, or Edu an admin must enable it first under **Settings → Permissions & Roles → Connected Data**.
2. Back in **Apps & Connectors**, click **Create** (sometimes **Create app** or **Add custom connector**).
3. Enter **Name** `ComStack` and **MCP Server URL** `https://api.comstack.ai/mcp`, set **Authentication** to **OAuth**, and tick **I trust this application**.
4. Click **Create**, then sign in with Google when the popup opens.
5. Use it in a chat: **+ → More → Developer mode → ComStack**.

OpenAI is renaming these menus (connectors → apps), so the labels may differ slightly; the path is the same.

### Claude Code

```bash
claude mcp add --transport http ComStack https://api.comstack.ai/mcp
```

### Machine access (CI, API keys)

For automation with no browser sign-in, authenticate with headers instead of OAuth:

```bash
curl -X POST https://api.comstack.ai/mcp \
  -H "Content-Type: application/json" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -H "x-api-key: YOUR_SERVICE_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get-project-state","arguments":{"project_id":"YOUR_PROJECT_ID"}}}'
```

Use a **service**-type API key (generate it in project settings); the `project_id` in each call must match the `x-project-id` header. Personal keys are deprecated for the MCP endpoint.

## First run

1. **Pick a workspace.** Experiment in a fresh trial project (the `create-project` tool, or the Account page) so first runs stay off any live site.
2. **Confirm the connection.** Ask the assistant to call `whoami` and `list-my-projects` — you should see your account and the project, with your role.
3. **Snapshot.** Have it call `get-project-state` for your `project_id`; read the `transformento://guide` resource (or `get-guide`) for the full workflow.
4. **Draft, approve, publish** with the prompts below — nothing goes live until you approve a `publish` manifest and the assistant runs `publish-confirm`.

## Example prompts

Paste these to a connected assistant (it will ask for or infer your `project_id`):

1. **Take stock —** *"Connect to my ComStack project `<PROJECT_ID>` and list my live and draft pages."*
2. **Create a page —** *"Create a knowledge page at slug `docs/hello` titled 'Hello from MCP' with a short intro. Show me the draft before publishing."*
3. **Edit a page —** *"Update the page at slug `docs/hello` to add a 'Next steps' section, then show me the draft URL."*
4. **Publish —** *"Publish my drafts. Show me the manifest first and wait for my go-ahead, then confirm and give me the live links."*
5. **Clean up —** *"Discard the draft at path `<DRAFT_PATH>` — I do not want to publish it."*

A good assistant always presents the `publish` manifest and the draft URL and waits for your explicit approval before calling `publish-confirm`.

## Use a test project

Because `publish` promotes **every** pending draft in a project at once, do your first runs in a dedicated test project: spin one up with `create-project`, verify the published URLs on that project's `site_url`, and only point the assistant at a production project once the flow feels predictable.

## Common errors

- **OAuth popup blocked** — allow popups for `api.comstack.ai` and reconnect.
- **`x-project-id` mismatch** — with API keys, the `project_id` in each call must equal the `x-project-id` header.
- **Tool not available / wrong role** — publishing needs the `manager` role; confirm via `list-my-projects`.
- **`project_name does not match`** — the assistant guessed it; tell it to read the name from `get-project-state`.
- **Nothing went live after `publish`** — `publish` is only a dry run; the assistant must also run `publish-confirm` and poll `publish-status`.

## Related

- [The standard MCP workflow](/docs/mcp/guide.md) — the loop your prompts drive
- [MCP OAuth and security](/docs/mcp/oauth.md) — sign-in, tokens, roles, safeguards
- [MCP tool catalogue](/docs/mcp/tools.md) — everything the assistant can call
- [ComStack Chrome Extension](/docs/chrome-extension.md) — capture web pages into drafts