Connect a desktop assistant (MCP server)

This page is the local setup: your assistant launches a small program on your own computer and talks to it, instead of reaching the app over a URL.

Most people do not need this. Claude Desktop and ChatGPT both take a Server URL and send you to your own Shopify admin to approve the access — no key to create, nothing to install. If that is all you want, follow Connect Claude or ChatGPT, no key needed instead and skip this page.

Stay here if:

your assistant only runs MCP servers on your computer — Cursor and most local MCP clients, or
your assistant would take a Server URL, but you would rather run the whole thing on your own machine.

Everything the assistant may see or change is decided by the key, not by this setup. Create the key first in Settings > Developers, ticking only what this assistant needs.

Before you start

A key from Settings > Developers (see MCP Keys). The value is shown once — copy it before closing the dialog.
Node.js (opens in a new tab) 20 or later on the same computer as the assistant.
The assistant's config file. For Claude Desktop:
- macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows — %APPDATA%\Claude\claude_desktop_config.json
Cursor and other MCP clients use the same mcpServers block in their own config file.

Add the server

There are two forms of the same configuration. Use the first one today.

Form 1 — run the built server (available now)

Build the server once, then point your assistant at the file it produced:

yarn workspace @avada/course-mcp run build

{
  "mcpServers": {
    "avada-course": {
      "command": "node",
      "args": ["/absolute/path/to/online-course/packages/mcp-cli/build/index.js"],
      "env": {
        "COURSE_MCP_KEY": "mcp_your-key-here"
      }
    }
  }
}

The path must be absolute — an assistant does not start in the folder you think it does.

Form 2 — `npx`, no build (coming soon)

Once the server is published to npm the same block becomes two lines, with nothing to build and no path to keep in sync:

{
  "mcpServers": {
    "avada-course": {
      "command": "npx",
      "args": ["-y", "@avada/course-mcp"],
      "env": {
        "COURSE_MCP_KEY": "mcp_your-key-here"
      }
    }
  }
}

⚠️

Not available yet. @avada/course-mcp is not on npm, so this block will fail with a "package not found" error today. It is documented here so you can switch to it later without changing anything else — the env block is identical. Use Form 1 until this note is removed.

Form 3 — install it once (coming soon)

npx reaches npm every time your assistant starts. Install the server instead if that does not suit you — a machine that is offline at startup, or a version you have tested and would rather stay on:

npm install -g @avada/course-mcp

The package installs a course-mcp command, so the assistant points straight at it — no build, no path, no args:

{
  "mcpServers": {
    "avada-course": {
      "command": "course-mcp",
      "env": {
        "COURSE_MCP_KEY": "mcp_your-key-here"
      }
    }
  }
}

Pin a version by installing that version — npm install -g @avada/[email protected] — and upgrade when you decide to. This waits on the same npm publish as Form 2; until then, Form 1 is the one that works.

Then restart your assistant — an MCP config is read at startup, not while it is running.

Allow changes (optional)

The server is read-only by default, even when your key carries write permissions. Holding a key is not the same as agreeing that an assistant may change your shop, so the opt-in is separate:

"env": {
  "COURSE_MCP_KEY": "mcp_your-key-here",
  "COURSE_MCP_ENABLE_WRITES": "true"
}

⚠️

"true" must be in quotes. It is a text value, not a JSON boolean — unquoted, your assistant rejects the whole configuration file and the server never starts.

A tool appears only when the key carries its permission and writes are enabled. Untick a permission on the key and the assistant simply never sees those tools.

Settings

Setting	Required	What it does
`COURSE_MCP_KEY`	Yes	Your key from Settings > Developers (starts with `mcp_`)
`COURSE_MCP_ENABLE_WRITES`	No	`"true"` (quoted) to allow changes. Permissions the key does not carry stay closed either way
`COURSE_API_URL`	No	Only for staging or local development. Refused for any host that is not an Online Course app host — your key travels in a request header

Check it works

Ask the assistant something simple, like "How many students are enrolled this month?"

Back in Settings > Developers, the line under the key's Status badge changes from Never used to the time it last answered. That is the quickest way to tell the connection is real.

What the assistant can do

Read — dashboard statistics, courses, modules, lessons, students and their progress, shop settings, portal translations.

Change (only when you enabled writes, and only for the permissions on the key) — create, update and delete courses, modules and lessons; reorder them; configure a course certificate; enroll a student; edit the General, Appearance and Notification settings; edit a notification email template; send a test email; edit a portal translation.

Long lists come back one page at a time. When more rows remain, the answer says so and names the cursor to ask for the next page — a good assistant follows that instead of reporting the first page as the total.

If something goes wrong

Message	What to do
`Missing COURSE_MCP_KEY`	The `env` block is missing, or the key is empty
`Authentication failed`	The key is wrong, was regenerated, or has expired — create a new one
`This key has expired`	Create a new key in Settings > Developers and paste the new value
`is not an Online Course app host`	`COURSE_API_URL` points somewhere your key must never be sent — remove it
`Rate limited`	60 requests per minute per key; the message says how long to wait
`package not found` on `npx`	You used Form 2 — it is not published yet, use Form 1
A tool is missing	The key does not carry that permission, or writes are not enabled

The server writes its log lines to your assistant's MCP log panel — that is where to look first.

What each permission unlocks — every permission and the tools it grants.
MCP Keys — create, edit, regenerate and delete keys, and connect an assistant over a Server URL instead — with a key, or by signing in with no key at all.

Permissions REST API