brilliant-directories-mcp

# 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-si