Skip to content
ComStack

Get started with the MCP server

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 — 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

Terminal window
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:

Terminal window
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.

Last updated: