Written for an AI agent to read and follow

Beaconed agent setup

Follow these five steps in order. If a step needs something from the human, stop and ask for it rather than guessing. Step 5 applies for the whole session.

1. Install the package

Install the MCP server globally. Node 20 or newer is required.

bash

npm install -g @beaconed/mcp

The command line tool is optional. Install it if the human wants to run Beaconed from a terminal or a script.

bash · optional

npm install -g @beaconed/cli

2. Get an API key from the human

Ask the human for a Beaconed API key. Keys look like bcn_live_... and are created in account settings. Do not attempt to create a key yourself, and do not proceed without one.

If the human has no account, send them to /app/registration/new and wait.
Store the key as an environment variable, not in a file you commit.
Never print the key back in full. Show the last four characters if you need to confirm which key is in use.

One key, one account. The key scopes you to that account and its connected stores. If the human runs several stores, ask which one this session is about.

3. Register the MCP server

For Claude Code, add the server from the command line:

bash · claude code

claude mcp add beaconed \
  --env BEACONED_API_KEY=bcn_live_... \
  -- npx -y @beaconed/mcp

For Claude Desktop, Cursor, Cline and Zed, add this block to the editor’s MCP configuration file and restart the editor:

json · desktop, cursor, cline, zed

{
  "mcpServers": {
    "beaconed": {
      "command": "npx",
      "args": ["-y", "@beaconed/mcp"],
      "env": { "BEACONED_API_KEY": "bcn_live_..." }
    }
  }
}

Config file locations differ per editor. Ask the human to confirm the path before you write to it.

4. Verify the connection

Ask the assistant to call beaconed_products_list with per_page: 1. A successful response confirms the MCP connection and API key work.

If you also installed the optional CLI, run beaconed auth login in your terminal and enter the same API key when prompted. Then check it separately:

bash

beaconed auth whoami
beaconed products list --per-page 1

A working CLI setup returns the account name and one product. If the account has no products yet, the list is empty and that is fine; say so rather than treating it as a failure.

Result	What to do
`401`	The key is wrong or revoked. Ask the human for a current key.
`403`	The key lacks the scope for that call. Report which call, and stop.
`429`	Rate limited. Back off and retry once, then report it.
`server not found`	The editor did not load the config. Confirm the file path and restart the editor.

5. Ground rules while you work

Ask before making any configuration change, to Beaconed settings, Autopilot guardrails or the editor’s own config.
Never publish without the human’s approval. Drafting and scoring are yours to run. Publishing is theirs to authorise, every time, including when Autopilot filled the queue.
Do not invent product facts. Drafts come from each product’s own description, images and fields. If a fact is missing, say it is missing.
Work in batches the human can review. Ten drafts they read beats two hundred they skim.
Report what you did in plain terms: how many products, which fields, what is waiting for approval.

If in doubt, stop and ask. The human is the author of their listings. You are the operator.