Official Brilliant Directories MCP Server — Setup Guide

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.

   Full walkthrough: How to Create an API Key.

3. Node.js — only for the Advanced path (see below). Not needed for the Easy path. If you need it, one-time install from nodejs.org (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
  • Claude Desktop
  • Claude Code
  • Claude extension inside Cursor
  • OpenAI (Codex Desktop)
  • Windsurf
  • Cline (VS Code extension)
  • Cursor
  • n8n
  • Make.com
  • Zapier
  • Abacus.AI (ChatLLM Agent)
  • curl / any HTTP client
• What you can ask the AI
• Updates are automatic
• Troubleshooting
• FAQ
• Authentication
• Rate Limits
• Pagination
• Filtering
• Sorting
• Available Resources
• Field Discovery
• Stable asset URLs
• Security
• Support

Setup by Platform

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 nodejs.org (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:

{
  "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).

⚠️ Claude Desktop doesn't accept the Easy block — use the Advanced block in the Claude Desktop section.

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".

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 nodejs.org → 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:

{
  "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 → → Quit , 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 claude.ai/download, 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) — your tools still work. Safe to ignore.

⚠️ STEP 1 — Install Node.js FIRST (before pasting the config below):

• Go to nodejs.org → 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:

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

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

After:

{
  "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 jsonlint.com 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 jsonlint.com
• 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 nodejs.org (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:

   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:

/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)

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)

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 nodejs.org → 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.

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

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 chatgpt.com/codex/get-started 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 nodejs.org → 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):

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