[primitives] Fix Cursor MCP connection docs (NateBJones-Projects#123)

* [docs] Fix Cursor MCP connection — use native url field, not mcp-remote

mcp-remote@latest now attempts OAuth client registration before sending
custom headers, which breaks against Open Brain's simple key-based auth.
Cursor supports remote MCP servers natively via the url field, so
mcp-remote is unnecessary.

Changes:
- Add dedicated Cursor section to getting-started guide (7.5) and
  remote-mcp primitive with native url config
- Update mcp-remote examples to pass key via ?key= query parameter
  instead of --header to avoid OAuth discovery issues
- Clarify x-brain-key (core) vs x-access-key (extensions) in
  troubleshooting guides

Made-with: Cursor

* [primitives] Bring remote MCP docs in line with repo format

---------

Co-authored-by: Jonathan Edwards <justfinethanku@gmail.com>

Author: 2 people

primitives/remote-mcp/README.md

@@ -3,13 +3,15 @@
 A guide to connecting your Open Brain extensions to any AI client. Deploy once as a Supabase Edge Function, connect from anywhere.
 
 **Jump to your client:**
-[Claude Desktop](#claude-desktop) | [ChatGPT](#chatgpt) | [Claude Code](#claude-code) | [Cursor / Windsurf / VS Code / Zed](#other-clients-cursor-windsurf-vs-code-zed) | [Troubleshooting](#troubleshooting)
+[Claude Desktop](#claude-desktop) | [ChatGPT](#chatgpt) | [Claude Code](#claude-code) | [Cursor](#cursor) | [Other Clients](#other-clients-windsurf-vs-code-zed) | [Troubleshooting](#troubleshooting)
 
-## What You Need
+## Prerequisites
 
 - Your **MCP Connection URL** (from the extension's credential tracker — looks like `https://YOUR_REF.supabase.co/functions/v1/extension-mcp?key=your-access-key`)
 - The AI client you want to connect
 
+## Step-by-step Instructions
+
 ## Claude Desktop
 
 1. Open Claude Desktop → **Settings** → **Connectors**
@@ -55,34 +57,48 @@ claude mcp add --transport http extension-name \
 
 Replace `extension-name` with a short name (e.g., `household-knowledge`, `family-calendar`), the URL with your MCP Server URL (without the `?key=` part), and `your-access-key` with your MCP Access Key.
 
-## Other Clients (Cursor, Windsurf, VS Code, Zed)
+## Cursor
+
+Cursor supports remote MCP servers natively. Add this to your `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "extension-name": {
+      "url": "https://YOUR_PROJECT_REF.supabase.co/functions/v1/extension-mcp?key=your-access-key"
+    }
+  }
+}
+```
+
+Restart Cursor and the extension's tools should appear in Settings → Features → MCP.
+
+> Do **not** use `mcp-remote` for Cursor. Newer versions of `mcp-remote` attempt OAuth client registration, which fails against Open Brain's simple key-based auth. Cursor's native `url` field works directly.
+
+## Other Clients (Windsurf, VS Code, Zed)
 
 Every MCP client handles remote servers slightly differently. Your extension accepts the access key two ways — pick whichever your client supports:
 
 **Option A: URL with key (easiest).** If your client has a field for a remote MCP server URL, paste the full MCP Connection URL including `?key=your-access-key`. This works for any client that supports remote MCP without requiring headers.
 
-**Option B: mcp-remote bridge.** If your client only supports local stdio servers (configured via a JSON config file), use `mcp-remote` to bridge to the remote server. This requires Node.js installed.
+**Option B: mcp-remote bridge (if your client only supports stdio).** Use `mcp-remote` to bridge to the remote server. This requires Node.js installed. Pass the access key via the URL query parameter (not a header) to avoid OAuth discovery issues with newer versions of `mcp-remote`:
 
 ```json
 {
   "mcpServers": {
     "extension-name": {
       "command": "npx",
       "args": [
+        "-y",
         "mcp-remote",
-        "https://YOUR_PROJECT_REF.supabase.co/functions/v1/extension-mcp",
-        "--header",
-        "x-access-key:${ACCESS_KEY}"
-      ],
-      "env": {
-        "ACCESS_KEY": "your-access-key"
-      }
+        "https://YOUR_PROJECT_REF.supabase.co/functions/v1/extension-mcp?key=your-access-key"
+      ]
     }
   }
 }
 ```
 
-> Note: no space after the colon in `x-access-key:${ACCESS_KEY}`. Some clients have a bug where spaces inside args get mangled.
+> Older examples pass the access key via `--header`. This breaks with `mcp-remote@latest` because it now attempts OAuth client registration before sending custom headers. Pass the key via the `?key=` query parameter instead.
 
 ## Troubleshooting
 
@@ -99,13 +115,18 @@ Every MCP client handles remote servers slightly differently. Your extension acc
 **Getting 401 errors**
 - The access key doesn't match what's stored in Supabase secrets
 - Double-check that the `?key=` value in your URL matches your MCP Access Key exactly
-- If using the header approach (Claude Code or mcp-remote), the header must be `x-access-key` (lowercase, with the dash)
+- If using the header approach (Claude Code), the core Open Brain server uses `x-brain-key` while extension servers use `x-access-key`
+- Prefer the `?key=` query parameter approach to avoid header name confusion
 
 **Tools work but responses are slow**
 - First request on a cold Edge Function takes a few seconds to warm up
 - Subsequent calls are faster
 - Check your Supabase project region — pick the one closest to you
 
+## Expected Outcome
+
+After following the steps for your client, your Open Brain extension should appear as a connected MCP server and its tools should be available inside that AI client without needing a local MCP bridge.
+
 ## Extensions That Use This
 
 - [Household Knowledge Base](../../extensions/household-knowledge/) (Extension 1)

primitives/troubleshooting/README.md

@@ -13,7 +13,8 @@ Solutions for issues that come up across any Open Brain extension. If your probl
 **"Getting 401 Unauthorized"**
 - The access key doesn't match what's stored in Supabase secrets
 - Double-check that the `?key=` value in your Connection URL matches your MCP Access Key exactly
-- If using header-based auth (Claude Code or mcp-remote), the header must be `x-access-key` (lowercase, with the dash)
+- If using header-based auth (Claude Code), the core Open Brain server expects `x-brain-key` while extension servers expect `x-access-key` — prefer using the `?key=` query parameter to avoid confusion
+- Do not use `mcp-remote` with `--header` for Cursor — use Cursor's native `url` field instead (see [Remote MCP Connection](../remote-mcp/))
 - Verify the secret is set: `supabase secrets list` should show `MCP_ACCESS_KEY`
 - Try regenerating the key: `openssl rand -hex 32`, then `supabase secrets set MCP_ACCESS_KEY=new-key` and update your Connection URL