brilliant-directories — плагин для Claude Code

# Official Brilliant Directories MCP Server — Setup Guide

[![npm version](https://img.shields.io/npm/v/brilliant-directories-mcp?color=blue&label=npm)](https://www.npmjs.com/package/brilliant-directories-mcp)
[![license](https://img.shields.io/github/license/brilliantdirectories/brilliant-directories-mcp?color=green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)

Universal AI integration for your BD site. Give any AI agent full access to your Brilliant Directories site with one API key.

Manage **members, posts (single-image and multi-image), leads, reviews, top and sub categories, email templates, pages (homepage, landing pages), 301 redirects, smart lists, widgets, menus, forms, tags, membership plans**, and more — across every resource BD exposes via its REST API.

This guide walks you through connecting your AI of choice (Claude, Cursor, etc.) to your BD site. Pick your AI app below, paste two things, restart. Most setups take under 5 minutes.

## ⚠️ REQUIREMENTS — Before you start

1. **Your BD site URL.** Use the full canonical URL exactly as it loads in a browser — include `https://` (or `http://` if your site has no SSL), include `www.` if your site uses it, no trailing slash.
   - ✅ `https://www.mysite.com` (most BD sites)
   - ✅ `https://mysite.com` (only if your site has no `www.`)
   - ✅ `http://mysite.com` (HTTP-only sites — protocol respected)
   - ❌ `mysite.com` (missing protocol)
   - ❌ `https://mysite.com/` (trailing slash)
   - ❌ `https://mysite.com` if the site actually serves at `www.mysite.com` — use the form your site canonically responds at
2. **Your BD API key.**

   BD Admin → **Developer Hub** → **Generate API Key** → copy it.

   <a href="https://support.brilliantdirectories.com/support/solutions/articles/12000088768" target="_blank" rel="noopener noreferrer">Full walkthrough: How to Create an API Key</a>.

3. **Node.js — only for the Advanced path** (see below). Not needed for the Easy path. If you need it, one-time install from <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> (click `Get Node.js®` to download, then click `Windows Installer (.msi)` — Mac: `macOS Installer` — double-click the downloaded file to install, Next through the prompts).

### 🚨 API PERMISSIONS — DO NOT SKIP THIS

**New BD API keys ship locked down — only member read/write is enabled by default.**

Every other resource (web pages, forms, menus, tags, email templates, reviews, leads, categories, post types, widgets, etc.) lives behind an **"Advanced Endpoints"** toggle and returns `403 API Key does not have permission to access this endpoint` until you flip it on.

**This catches almost every first-time user.** If your AI can list members but can't create a page or update a form, stop debugging — it's this.

**Turn on Advanced Endpoints:**

1. BD Admin → **Developer Hub**
2. Find your API key in the list → **Actions** dropdown → **Permissions**
3. Click the **Advanced Endpoints** tab
4. Toggle everything **ON** (or cherry-pick only the resources you'll use — but ALL ON is the fastest way to stop tripping over this)
5. Click **Save Permissions**

The change is immediate — no key rotation, no AI restart needed. Re-run the failed request and it'll succeed.

> **Want to stop the AI from deleting anything?** Uncheck every `delete` action under Advanced Endpoints. The AI will still be able to read, create, and update — but any `delete*` tool call will return 403 instead of wiping data. Good baseline for production sites where the AI shouldn't be trusted with destructive operations.

> **Why BD locks it down by default:** least-privilege. A leaked key with baseline-only permissions can only read/write members on your site, not rewrite your whole directory. Once you've decided which endpoints your agent actually needs, you can pare the permissions back down to just those.

## Table of Contents

- [Setup by Platform](#setup-by-platform)
  - [Claude Desktop](#claude-desktop)
  - [Claude Code](#claude-code)
  - [Claude extension inside Cursor](#claude-extension-inside-cursor)
  - [OpenAI (Codex Desktop)](#openai-codex-desktop)
  - [Windsurf](#windsurf)
  - [Cline (VS Code extension)](#cline-vs-code-extension)
  - [Cursor](#cursor)
  - [n8n](#n8n)
  - [Make.com](#makecom)
  - [Zapier](#zapier)
  - [Abacus.AI (ChatLLM Agent)](#abacusai-chatllm-agent)
  - [curl / any HTTP client](#curl--any-http-client)
- [What you can ask the AI](#what-you-can-ask-the-ai)
- [Updates are automatic](#updates-are-automatic)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
- [Authentication](#authentication)
- [Rate Limits](#rate-limits)
- [Pagination](#pagination)
- [Filtering](#filtering)
- [Sorting](#sorting)
- [Available Resources](#available-resources)
- [Field Discovery](#field-discovery)
- [Stable asset URLs](#stable-asset-urls)
- [Security](#security)
- [Support](#support)

## Setup by Platform

<a id="the-config-block"></a>

Each platform has **two options**:

- **🚀 Easy config block** — points at our hosted MCP at `https://brilliantmcp.com`. No Node.js, no install, no terminal. Starts working the moment you save and restart your AI app.
- **🛠️ Advanced config block** — spawns the MCP as a `npx` child process on your machine. Use when you want the MCP on your own hardware.

  **Needs Node.js installed first** — get it from <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> (click `Get Node.js®` to download, then click `Windows Installer (.msi)` — Mac: `macOS Installer` — and DOUBLE-CLICK the downloaded file to install it).

**Both give the full BD tool surface, same instructions, same lean shapers, same safety guards.**

### 🚀 Easy config block (recommended — 30-second install)

In your AI client's MCP config (Cursor, Windsurf, Cline, Codex, n8n, etc.), add this entry:

```json
{
  "mcpServers": {
    "brilliant-directories": {
      "url": "https://brilliantmcp.com",
      "headers": {
        "X-Api-Key": "ENTER_API_KEY",
        "X-BD-Site-URL": "https://www.your-site.com"
      }
    }
  }
}
```

Replace `ENTER_API_KEY` with your BD API key and `https://www.your-site.com` with your BD site URL (full canonical form — `https://`, exact host, no trailing slash, see [Requirements](#requirements--before-you-start)).

> ⚠️ **Claude Desktop doesn't accept the Easy block** — use the Advanced block in the [Claude Desktop section](#claude-desktop).

**Save, then fully quit and reopen the AI app.** Saving alone is not enough — every AI client loads MCP servers only at fresh launch, not on hot-reload. Done. Working? [Skip to "What you can ask the AI"](#what-you-can-ask-the-ai).

Need a client-specific walkthrough? Jump to your platform's section below.

### 🛠️ Advanced config block (requires Node.js install)

> ⚠️ **STEP 1 — Install Node.js FIRST** (the Advanced path runs an `npx` command on your machine):
> - Go to <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> → click **Get Node.js®**
> - Download: **Windows Installer (.msi)** or **macOS Installer**
> - Double-click the file → click Next through every prompt to fully install Node.js
>
> Skip this and you'll see *"no MCP servers"* with `spawn npx ENOENT` in the log.

> **Why `--prefer-online` + `@latest`?** Forces npm to revalidate against the registry on every launch so you always pull the newest version. Prevents the `ETARGET No matching version found` error that hits when your local npm cache is stale.

**STEP 2 — Paste this config:**

```json
{
  "mcpServers": {
    "brilliant-directories": {
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "brilliant-directories-mcp@latest",
        "--api-key", "ENTER_API_KEY",
        "--url", "https://www.your-site.com"
      ]
    }
  }
}
```

**STEP 3 — Fully quit the AI app, then reopen.** Closing the window is NOT enough — the AI loads MCP servers only at a true relaunch:
- **Windows:** right-click the app's icon in the system tray (bottom-right, may be hidden under `^`) → **Quit**, then reopen
- **Mac:** `Cmd+Q` or menu bar → **<App>** → **Quit <App>**, then reopen

---

### Claude Desktop

> ⚠️ **Claude Desktop requires Node.js + the Advanced (npm) config.** It doesn't accept the Easy `url`-shaped block — only stdio (`command` + `args`).

> ⚠️ **Windows users:** install Claude Desktop from <a href="https://claude.ai/download" target="_blank" rel="noopener noreferrer">claude.ai/download</a>, NOT the Microsoft Store (the Store version sandboxes the config file).

> **Banner saying "Tool result could not be submitted… connection interrupted"?** Cosmetic UI bug across every MCP connector ([anthropics/claude-code #51874](https://github.com/anthropics/claude-code/issues/51874)) — your tools still work. Safe to ignore.

> ⚠️ **STEP 1 — Install Node.js FIRST** (before pasting the config below):
> - Go to <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> → click **Get Node.js®**
> - Download: **Windows Installer (.msi)** or **macOS Installer**
> - Double-click the file → click Next through every prompt to fully install Node.js
>
> Skip this and you'll see *"no MCP servers"* with `spawn npx ENOENT` in the log.

**Steps (no terminal):**

1. Open Claude Desktop.
2. Menu bar → **Settings**.

   **Developer tab → Edit Config**.

   This opens `claude_desktop_config.json` in TextEdit (Mac) or Notepad (Windows).
3. Pick your scenario:

#### Scenario A — file is empty `{}` or has no `mcpServers` entry

Select all (`Cmd+A` / `Ctrl+A`) and delete. Paste this:

```json
{
  "mcpServers": {
    "brilliant-directories": {
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "brilliant-directories-mcp@latest",
        "--api-key", "ENTER_API_KEY",
        "--url", "https://www.your-site.com"
      ]
    }
  }
}
```

Replace `ENTER_API_KEY` with your BD API key and `https://www.your-site.com` with your BD site URL. **Save, then fully quit and reopen Claude Desktop.** Saving alone is not enough — Claude loads MCP servers only at fresh launch.

#### Scenario B — file already has content (preferences, Google connectors, other MCP servers)

Merge — don't overwrite. Two rules:
- Comma between top-level entries.
- Final `}` at the bottom stays one brace.

**Before:**

```json
{
  "preferences": {
    "menuBarEnabled": false,
    "legacyQuickEntryEnabled": false
  }
}
```

**After:**

```json
{
  "preferences": {
    "menuBarEnabled": false,
    "legacyQuickEntryEnabled": false
  },
  "mcpServers": {
    "brilliant-directories": {
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "brilliant-directories-mcp@latest",
        "--api-key", "ENTER_API_KEY",
        "--url", "https://www.your-site.com"
      ]
    }
  }
}
```

Two changes: `,` added after the `preferences` closing `}`, and the `mcpServers` block added before the final `}`. Replace `ENTER_API_KEY` with your BD API key and `https://www.your-site.com` with your BD site URL. **Save, then fully quit and reopen Claude Desktop.**

> **Paste your final file into <a href="https://jsonlint.com" target="_blank" rel="noopener noreferrer">jsonlint.com</a> before restarting to ensure correct formatting.**
>
> Missing commas silently break the MCP — a validator flags them instantly.

---

4. **Fully quit and reopen Claude Desktop.** Start a new chat.

   > **"Fully quit" means more than closing the window** — Claude loads MCP servers only at a true relaunch:
   > - **Windows:** right-click the Claude icon in the system tray (bottom-right, may be hidden under `^`) → **Quit**, then reopen
   > - **Mac:** `Cmd+Q` or menu bar → **Claude** → **Quit Claude**, then reopen
5. **Verify the BD MCP loaded.** The exact UI varies by Claude Desktop version:
   - In any chat, ask **"what tools do you have?"** — you should see `brilliant-directories` tools listed.
   - OR check **Settings → Developer → MCP servers** — `brilliant-directories` should show as connected (no error status).
   - Older builds also show a **🔨 hammer icon** with a tool count near the chat input — click it to see the tools.

> **Not connected?** Check **Settings → Developer → MCP servers** for the error. Common causes:
> - JSON typo — paste your file into <a href="https://jsonlint.com" target="_blank" rel="noopener noreferrer">jsonlint.com</a>
> - Wrong API key, or URL missing `https://` / has trailing slash
> - Node.js not installed (Claude Desktop spawns `npx`)
> - Saw *"not valid MCP server configurations"*? You pasted a `url`-shaped block — Claude Desktop only accepts the stdio (`command` + `args`) shape shown above.

**Direct config file path** (if you skip Settings):
- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

---

### Claude Code

Claude Code has no MCP GUI — install via terminal. Works in Terminal.app (Mac), PowerShell (Windows), or Cursor / VS Code's built-in terminal (open with ``Ctrl+` `` / ``Cmd+` `` or **View → Terminal**).

**Prerequisites — one-time install:**

1. **Node.js** — from <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> (click `Get Node.js®` → `Windows Installer (.msi)` or `macOS Installer` → double-click to install, click Next through the prompts).
2. **The `claude` CLI** — in any terminal, run:

   ```bash
   npm install -g @anthropic-ai/claude-code
   ```

   Close and reopen the terminal. Verify with `claude --version`.

Three options below — pick whichever fits.

#### ⚡ Plugin (one-line install, recommended if your Claude Code supports it)

Inside an active `claude` session, run these two slash commands:

```text
/plugin marketplace add brilliantdirectories/brilliant-directories-mcp
/plugin install brilliant-directories@brilliant-directories-mcp
```

Claude Code fetches the plugin manifest, registers the BD MCP server, and tools become available immediately. You'll be prompted for `BD_API_KEY` and `BD_SITE_URL` on first use, or set them as environment variables before launching `claude`. (The Easy and Advanced paths below take credentials inline in the `claude mcp add` command instead — different paths, same end result.)

> **Don't see `/plugin` commands?** Plugin support requires a recent build. Run `npm install -g @anthropic-ai/claude-code@latest` and restart the terminal. If still missing, use the Easy or Advanced path below.

#### 🚀 Easy (hosted Worker — no local BD MCP subprocess)

```bash
claude mcp add brilliant-directories --transport http https://brilliantmcp.com \
  --header "X-Api-Key: ENTER_API_KEY" \
  --header "X-BD-Site-URL: https://www.your-site.com"
```

Replace `ENTER_API_KEY` with your BD API key and `https://www.your-site.com` with your BD site URL. Verify with `claude mcp list` — `brilliant-directories` should show `✓ Connected`. Close and reopen Claude Code.

#### 🛠️ Advanced (BD MCP runs locally via `npx`)

```bash
claude mcp add brilliant-directories -- npx -y --prefer-online brilliant-directories-mcp@latest --api-key ENTER_API_KEY --url https://www.your-site.com
```

Same shape, but runs the MCP server as an `npx` child process on your machine. Replace the placeholders. Verify with `claude mcp list`. Close and reopen Claude Code. The `-y` flag auto-accepts the first-time npx install prompt so the spawn doesn't hang.

> **Credentials live inside the `claude mcp add` command.** They're written into your user-level Claude config file and passed to BD automatically on every tool call. To rotate: `claude mcp remove brilliant-directories`, then re-run `claude mcp add` with new values.

---

### Claude extension inside Cursor

If you chat with Claude inside Cursor (the Anthropic "Claude" extension installed from the Cursor extension marketplace), that extension has its OWN MCP config — **separate from Cursor's native agent.** Installing in one doesn't install in the other.

> **Note:** the Claude extension and the Claude Code CLI both read the SAME file — `~/.claude.json` (Windows: `C:\Users\<you>\.claude.json`). If you've already set up Claude Code per the section above, the BD MCP is already loaded for the Claude extension too. This section covers customers who only use the Claude extension and don't have the CLI installed.

**Two different MCP configs. Two different places the tools show up.**

**1. Claude extension (inside Cursor or Claude Code CLI)**
- Config file (Windows): `C:\Users\<you>\.claude.json`
- Config file (Mac / Linux): `~/.claude.json`
- Tools appear: when you chat with Claude — ask *"what tools do you have"* or type `/mcp`

**2. Cursor's native agent**
- Config file (Windows): `C:\Users\<you>\.cursor\mcp.json`
- Config file (Mac / Linux): `~/.cursor/mcp.json`
- Tools appear: Cursor **Settings → Tools & MCP**

**Easiest setup — edit the JSON file in Notepad (NO terminal, NO `claude` CLI needed):**

> ⚠️ **STEP 1 — Install Node.js FIRST** (before editing the config below):
> - Go to <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> → click **Get Node.js®**
> - Download: **Windows Installer (.msi)** or **macOS Installer**
> - Double-click the file → click Next through every prompt to fully install Node.js
>
> Skip this and you'll see *"no MCP servers"* with `spawn npx ENOENT` in the log.

1. **Open the file.** Paste the path into File Explorer's address bar (Windows) or Finder's **Go → Go to Folder** (Mac). If it doesn't exist yet, create a new empty text file at that path named exactly `.claude.json`.
2. **Paste this inside.** If the file already has content with an `mcpServers` key, merge the `"brilliant-directories": {...}` entry into the existing `mcpServers` object — don't overwrite other entries.

   ```json
   {
     "mcpServers": {
       "brilliant-directories": {
         "command": "npx",
         "args": [
           "-y",
           "--prefer-online",
           "brilliant-directories-mcp@latest",
           "--api-key", "ENTER_API_KEY",
           "--url", "https://www.your-site.com"
         ]
       }
     }
   }
   ```

3. Replace `ENTER_API_KEY` with your BD API key and `https://www.your-site.com` with your BD site URL (include `https://`, no trailing slash).
4. **Save the file, then fully quit and reopen Cursor** so the Claude extension picks up the new config. Saving alone is not enough.
5. Chat with Claude and ask *"what tools do you have?"* — you should see `brilliant-directories` tools listed.

> **Cursor's Tools & MCP panel will stay empty — that's expected.** Claude's extension reads `~/.claude.json`; Cursor's panel only reflects `~/.cursor/mcp.json`. If you want BD tools in BOTH surfaces, also do the [Cursor section](#cursor) install.

**Alternative — if you have the `claude` CLI installed** (most users don't — skip if you don't know what it is): run this in any terminal:

```bash
claude mcp add brilliant-directories -- npx -y --prefer-online brilliant-directories-mcp@latest --api-key ENTER_API_KEY --url https://www.your-site.com
```

The CLI writes the same JSON to `~/.claude.json` for you — same end result as editing by hand.

---

### OpenAI (Codex Desktop)

| OpenAI surface | Supported? |
|---|---|
| **Codex Desktop** (the desktop app) | ✅ **Yes — full MCP, both transports** |
| ChatGPT web / desktop / mobile | ❌ No — no MCP connector support in consumer ChatGPT |

For BD automation in the OpenAI ecosystem, use **Codex Desktop**. ChatGPT itself can't speak MCP yet; for GUI alternatives if you don't want Codex, use Claude Desktop / Cursor / Windsurf / Cline.

#### Codex Desktop setup

**1. Download Codex Desktop** from <a href="https://chatgpt.com/codex/get-started/" target="_blank" rel="noopener noreferrer">chatgpt.com/codex/get-started</a> and install it.

**2. Open Codex Desktop** → **File** → **Settings** → **MCP Servers** → **+ Add Server**.

A "Connect to a custom MCP" form opens with two tabs: **STDIO** (Advanced — runs locally, needs Node.js) and **Streamable HTTP** (Easy — hosted Worker, no Node.js). Either works — pick one.

**🚀 Easy (Streamable HTTP — recommended, no Node.js install required):**

Click the **Streamable HTTP** tab. Fill the form top-to-bottom:

| Field (as shown in Codex) | Value |
|---|---|
| **Name** | `Brilliant Directories` (or any label) |
| **URL** | `https://brilliantmcp.com` |
| **Bearer token env var** | *leave empty — don't touch* |
| **Headers** — Key | `X-Api-Key` |
| **Headers** — Value | your BD API key |
| *Click **+ Add header** to add the second row* | |
| **Headers** — Key (row 2) | `X-BD-Site-URL` |
| **Headers** — Value (row 2) | `https://www.your-site.com` |
| **Headers from environment variables** | *leave empty — don't touch* |

**Click Save, then fully quit and reopen Codex.** Saving alone is not enough — Codex loads MCP servers only at fresh launch.

**🛠️ Advanced (STDIO — runs on your machine, needs Node.js):**

> ⚠️ **STEP 1 — Install Node.js FIRST** (before pasting the config below):
> - Go to <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> → click **Get Node.js®**
> - Download: **Windows Installer (.msi)** or **macOS Installer**
> - Double-click the file → click Next through every prompt to fully install Node.js
>
> Skip this and you'll see *"no MCP servers"* with `spawn npx ENOENT` in the log.

Click the **STDIO** tab. Fill the form top-to-bottom:

| Field (as shown in Codex) | Value |
|---|---|
| **Name** | `Brilliant Directories` (or any label) |
| **Command to launch** | `npx` |
| **Arguments** — Row 1 | `-y` |
| *Click **+ Add argument** between each row below* | |
| **Arguments** — Row 2 | `brilliant-directories-mcp@latest` |
| **Arguments** — Row 3 | `--api-key` |
| **Arguments** — Row 4 | your BD API key |
| **Arguments** — Row 5 | `--url` |
| **Arguments** — Row 6 | `https://www.your-site.com` |
| **Environment variables** | *leave empty — don't touch* |
| **Environment variable passthrough** | *leave empty — don't touch* |
| **Working directory** | *leave empty — don't touch* |

**Click Save, then fully quit and reopen Codex.** Saving alone is not enough — Codex loads MCP servers only at fresh launch.

> **"Fully quit" means more than closing the window** — Codex loads MCP servers only at a true relaunch:
> - **Windows:** right-click the Codex icon in the system tray (bottom-right, may be hidden under `^`) → **Quit**, then reopen
> - **Mac:** `Cmd+Q` or menu bar → **Codex** → **Quit Codex**, then reopen

**4. Test the connection:** in a new Codex chat, ask *"list my first 5 members on my BD site"*. Tools invoke, data comes back.

> **Pro tip — multi-site management:** repeat this setup with a different **Name** + credentials per BD site (e.g. `brilliant-directories-main` / `brilliant-directories-staging`). Then tell Codex *"on brilliant-directories-main, list the top categories"* or *"copy these email templates from -main to -staging"*. Useful for agencies and multi-brand operators.

---

### Windsurf

Windsurf's AI pane is called **Cascade**. MCP servers plug into Cascade.

> ⚠️ **Windsurf uses `serverUrl` (not `url`) for remote MCP servers.** The Easy config block below reflects that.

1. Open Windsurf.
2. Open settings: click **Windsurf - Settings** at the bottom-right of the window, OR Command Palette (`Cmd/Ctrl+Shift+P`) → type `Open Windsurf Settings`.
3. In settings, find the **Cascade** section → **Model Context Protocol (MCP)** → enable it.
4. In the Cascade panel on the right of your window, click the **MCPs icon** (top-right of the panel) → **Configure**. This opens the MCP config file.
5. Paste **one of these** (Easy is recommended):

**🚀 Easy (recommended — no Node.js install required):**

```json
{
  "mcpServers": {
    "brilliant-directories": {
      "serverUrl": "https://brilliantmcp.com",
      "headers": {
        "X-Api-Key": "ENTER_API_KEY",
        "X-BD-Site-URL": "https://www.your-site.com"
      }
    }
  }
}
```

**🛠️ Advanced (runs on your machine, needs Node.js):**

> ⚠️ **STEP 1 — Install Node.js FIRST** (before pasting the config below):
> - Go to <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> → click **Get Node.js®**
> - Download: **Windows Installer (.msi)** or **macOS Installer**
> - Double-click the file → click Next through every prompt to fully install Node.js
>
> Skip this and you'll see *"no MCP servers"* with `spawn npx ENOENT` in the log.

```json
{
  "mcpServers": {
    "brilliant-directories": {
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "brilliant-directories-mcp@latest",
        "--api-key", "ENTER_API_KEY",
        "--url", "https://www.your-site.com"
      ]
    }
  }
}
```

Replace `ENTER_API_KEY` with your BD API key and `https://www.your-site.com` with your BD site URL. **Save, then fully quit and reopen Windsurf.** Saving alone is not enough — Windsurf loads MCP servers only at fresh launch.

   > **"Fully quit" means more than closing the window** — Windsurf loads MCP servers only at a true relaunch:
   > - **Windows:** right-click the Windsurf icon in the system tray (bottom-right, may be hidden under `^`) → **Quit**, then reopen
   > - **Mac:** `Cmd+Q` or menu bar → **Windsurf** → **Quit Windsurf**, then reopen

---

### Cline (VS Code extension)

1. Open VS Code with the **Cline** extension installed.
2. Click the **Cline icon** in the VS Code sidebar to open the Cline panel.
3. In Cline's top nav, click the **MCP Servers icon**.
4. Click **Configure MCP Servers** — opens the Cline MCP config file in VS Code.
5. Paste **one of these** (Easy is recommended):

**🚀 Easy (recommended — no Node.js install required):**

```json
{
  "mcpServers": {
    "brilliant-directories": {
      "url": "https://brilliantmcp.com",
      "headers": {
        "X-Api-Key": "ENTER_API_KEY",
        "X-BD-Site-URL": "https://www.your-site.com"
      }
    }
  }
}
```

**🛠️ Advanced (runs on your machine, needs Node.js):**

> ⚠️ **STEP 1 — Install Node.js FIRST** (before pasting the config below):
> - Go to <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> → click **Get Node.js®**
> - Download: **Windows Installer (.msi)** or **macOS Installer**
> - Double-click the file → click Next through every prompt to fully install Node.js
>
> Skip this and you'll see *"no MCP servers"* with `spawn npx ENOENT` in the log.

```json
{
  "mcpServers": {
    "brilliant-directories": {
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "brilliant-directories-mcp@latest",
        "--api-key", "ENTER_API_KEY",
        "--url", "https://www.your-site.com"
      ]
    }
  }
}
```

Replace `ENTER_API_KEY` with your BD API key and `https://www.your-site.com` with your BD site URL. **Save, then fully quit and reopen VS Code.** Saving alone is not enough — Cline loads MCP servers only at fresh launch, not on panel reload or toggle.

6. Back in the MCP Servers panel, confirm `brilliant-directories` appears — toggle it **on** if not already.

   > **"Fully quit" means more than closing the window** — Cline loads MCP servers only at a true VS Code relaunch:
   > - **Windows:** right-click the VS Code icon in the system tray (bottom-right, may be hidden under `^`) → **Quit**, then reopen
   > - **Mac:** `Cmd+Q` or menu bar → **Code** → **Quit Visual Studio Code**, then reopen

---

### Cursor

> **Fastest path (no install, 30 seconds):** open Cursor Settings → **MCP** (or **Model Context Protocol**) → **Add new MCP server** → paste the [Easy config block](#setup-by-platform) with your API key + site URL. Fully quit + reopen. Tools appear in the chat.
>
> Or edit `~/.cursor/mcp.json` directly and paste the block. Either way works.
>
> Prefer the local install? Keep reading — the Cursor Directory installer below sets up the Advanced path (runs as an npx child process).

**Cursor Directory one-click install for the Advanced path (no terminal, no file editing):**

> ⚠️ **STEP 1 — Install Node.js FIRST** (the Cursor Directory installer wires up an `npx` child process):
> - Go to <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> → click **Get Node.js®**
> - Download: **Windows Installer (.msi)** or **macOS Installer**
> - Double-click the file → click Next through every prompt to fully install Node.js
>
> Skip this and Cursor will show *"no MCP servers"* with `spawn npx ENOENT` in the log.

1. **Open** → <a href="https://cursor.directory/plugins/brilliant-directories" target="_blank" rel="noopener noreferrer">cursor.directory/plugins/brilliant-directories</a>
2. Click **Install** / **Add to Cursor** → allow browser to open Cursor.
3. Cursor shows an **"Install MCP Server?"** prompt with most fields pre-filled. Two things you need to change:

   **Rename the Name field** (don't leave it as `server` — too generic):
   - `brilliant-directories-60031` — site-ID-based (recommended pattern)
   - `brilliant-directories-mysite` — site-name-based
   - `brilliant-directories-main` / `brilliant-directories-staging` / `brilliant-directories-client-acme` — nickname
   - Why: Cursor lists every MCP by this Name; if you later add a second BD site, you'll need to tell them apart.

   **Fill Environment Variables — RIGHT side only:**

   | Left (do NOT touch) | Right (paste your values) |
   |---|---|
   | `BD_API_KEY` | your BD API key |
   | `BD_SITE_URL` | `https://www.your-site.com` — include `https://`, no trailing slash |

   - API key → BD Admin → **Developer Hub** → **Generate API Key** (BD shows it once; if lost, generate a new one).
   - Advanced endpoint permissions must be enabled on the key or most writes 403. See [Before you start](#requirements--before-you-start).

4. Click **Install**.
5. **Fully quit and reopen Cursor.**

   > **"Fully quit" means more than closing the window** — Cursor loads MCP servers onl...