Written for an AI agent to read and follow

Beaconed agent setup

If your client supports remote MCP connectors, connect to the hosted server below: there is nothing to install and no API key. Otherwise, install the server locally. If a step needs something from the human, stop and ask for it rather than guessing. The ground rules at the end apply either way, for the whole session.

Connect the hosted server

The server address is:

https://mcp.beaconed.ai/mcp

1. Give the human the address and ask them to add it as a custom connector. In Claude that is Settings, then Connectors, then Add custom connector. Other clients that support remote MCP connectors have an equivalent setting.
2. The client opens a Beaconed sign-in. The human signs in, picks the account to connect (one they own or administer), reviews what the connection may do, and chooses Allow access. Beaconed names the client and marks it unverified; that is expected.
3. Do not ask for an API key. The hosted connection does not use one.

Then call beaconed_products_list with per_page: 1. A successful response confirms the connection. If the account has no products yet, the list is empty and that is fine; say so rather than treating it as a failure.

The human can see and disconnect every connection at beaconed.ai/mcp/connections. Access expires after 90 days.

Or install the server locally

Use this path when your client cannot add remote MCP connectors. Follow these four steps in order.

1. Install the package

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

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.

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.

3. Register the MCP server

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

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:

{
  "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:

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.

Ground rules while you work

1. Ask before making any configuration change, to Beaconed settings, Autopilot guardrails or the editor’s own config.
2. 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.
3. 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.
4. Work in batches the human can review. Ten drafts they read beats two hundred they skim.
5. Report what you did in plain terms: how many products, which fields, what is waiting for approval.