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

[matthallett1]

Summary

• Adds a dedicated Cursor section (7.5) to the getting-started guide and remote-mcp primitive with native url config — no mcp-remote needed.
• Updates the mcp-remote fallback examples (for clients that still need stdio bridging) to pass the access key via ?key= query parameter instead of --header, avoiding OAuth client registration failures with mcp-remote@latest.
• Clarifies that the core Open Brain server uses x-brain-key while extension servers use x-access-key in the troubleshooting guides.

Why

mcp-remote@latest now defaults to http-first transport, which attempts OAuth client registration before forwarding custom headers. Open Brain uses simple key-based auth (not OAuth), so this registration attempt fails with a ServerError. Since Cursor natively supports remote MCP servers via the url field (like Sentry's config), mcp-remote is unnecessary and actively harmful.

Files changed

• docs/01-getting-started.md — Split "Other Clients" into dedicated Cursor (7.5) and Other Clients (7.6) sections
• primitives/remote-mcp/README.md — Added Cursor section, updated mcp-remote examples, fixed 401 troubleshooting
• primitives/troubleshooting/README.md — Clarified header names and added Cursor-specific guidance

Test plan

• Verified Cursor connects successfully with native url field config (~/.cursor/mcp.json)
• Verified mcp-remote with ?key= query parameter works for stdio-only clients
• Confirmed mcp-remote with --header fails with OAuth ServerError on mcp-remote@latest

Made with Cursor

[github-actions]

OB1 Automated Review

This PR modifies docs or repo governance files. Contribution checks skipped.

✅ No issues found.

[matthallett1]

@claude review this PR

[matthallett1]

@claude review this PR

[github-actions]

Claude finished @matthallett1's task in 1m 6s —— View job

---

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

• Read changed files
• Review docs/01-getting-started.md
• Review primitives/remote-mcp/README.md
• Review primitives/troubleshooting/README.md
• Post final review

---

Summary

This is a solid, well-scoped docs fix that addresses a real breakage introduced by mcp-remote@latest. The technical reasoning is sound and the changes are consistent across all three files. I have a few minor observations but nothing blocking.

---

What Works Well

Technically correct. The diagnosis is accurate — mcp-remote@latest now uses http-first transport and attempts OAuth client registration before forwarding custom headers. Since Open Brain uses simple key-based auth, this registration fails with a ServerError. Moving Cursor users to the native url field is the right call.

Consistent changes across files. The fix is applied in all three relevant places: docs/01-getting-started.md (step 7.5), primitives/remote-mcp/README.md, and primitives/troubleshooting/README.md. Good coverage.

Useful separation of concerns. Splitting "Other Clients" into a dedicated Cursor section (7.5) and a general stdio-bridge section (7.6) makes the guide easier to follow. Users who just need Cursor don't have to parse through mcp-remote options.

The ?key= query parameter approach is pragmatic. For clients that genuinely need mcp-remote (stdio-only), documenting the key via query param instead of --header avoids the OAuth issue for those cases too.

The warning note is well-placed. The "do not use mcp-remote for Cursor" callout in both the getting-started guide (line 733) and the remote-mcp primitive (line 74) proactively stops users who might copy an older example.

---

Minor Observations

The x-brain-key vs x-access-key clarification is slightly buried. The troubleshooting README (primitives/troubleshooting/README.md:16) now says:

If using header-based auth (Claude Code), the core Open Brain server expects x-brain-key while extension servers expect x-access-key

This is accurate and useful. However, the same nuance in docs/01-getting-started.md (line 828) only mentions x-brain-key without the extension distinction. Not a blocker, but worth noting for consistency.

Claude Code section still uses --header (primitives/remote-mcp/README.md:53):

--header "x-access-key: your-access-key"

This is intentional — Claude Code's native --header flag doesn't go through mcp-remote, so it doesn't hit the OAuth issue. But it could confuse readers who just read the "don't use --header" warning above it. A one-line comment like # Claude Code uses native headers — not mcp-remote, so this works fine would prevent that confusion. Not required.

No test instructions for "Other Clients." The PR's test plan covers Cursor and mcp-remote with ?key=, which is the important part. Not a gap.

---

Alignment with OB1 Standards

• No credentials or secrets introduced
• No core thoughts table changes
• No local MCP servers — all instructions point to remote Edge Functions
• No binary blobs or unqualified SQL
• Docs-only change, so no metadata.json required

---

Verdict

Approve. This fixes a real, user-facing breakage caused by an upstream mcp-remote change and is well-documented across the relevant files. The minor note about the x-brain-key vs x-access-key wording in 01-getting-started.md:828 is cosmetic and can be addressed in a follow-up if desired.