remote-mcp

Remote MCP Connection

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 | ChatGPT | Claude Code | Cursor | Other Clients | Troubleshooting

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
2. Click Add custom connector
3. Name: the extension name (e.g., Household Knowledge, Family Calendar)
4. Remote MCP server URL: paste your MCP Connection URL
5. Click Add

Start a new conversation and enable the connector via the "+" button at the bottom of the chat → Connectors.

You can add multiple extensions as separate connectors and toggle them per conversation.

ChatGPT

Requires a paid ChatGPT plan (Plus, Pro, Business, Enterprise, or Edu). Works on the web at chatgpt.com — not available on mobile.

Enable Developer Mode (one-time setup):

1. Go to chatgpt.com → click your profile icon → Settings
2. Navigate to Apps & Connectors → Advanced settings
3. Toggle Developer mode ON

Enabling Developer Mode disables ChatGPT's built-in Memory feature. Your Open Brain replaces that functionality — and it works across every AI, not just ChatGPT.

Add the connector:

1. In Settings → Apps & Connectors, click Create
2. Name: the extension name
3. Description: brief description of what it does (for your reference only)
4. MCP endpoint URL: paste your MCP Connection URL
5. Authentication: select No Authentication (your access key is embedded in the URL)
6. Click Create

Using it: Start a new conversation and make sure the connector is enabled in the tools/apps panel. ChatGPT sometimes needs explicit tool references: "Use the search_household_items tool to find my paint colors."

Claude Code

claude mcp add --transport http extension-name \
  https://YOUR_PROJECT_REF.supabase.co/functions/v1/extension-mcp \
  --header "x-access-key: your-access-key"

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.

Cursor

Cursor supports remote MCP servers natively. Add this to your ~/.cursor/mcp.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 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:

{
  "mcpServers": {
    "extension-name": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR_PROJECT_REF.supabase.co/functions/v1/extension-mcp?key=your-access-key"
      ]
    }
  }
}

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

Claude Desktop tools don't appear

• Make sure the connector is enabled for your conversation — click "+" → Connectors and check the toggle
• Verify the MCP Connection URL is correct (it should end with ?key=your-access-key)
• Try removing and re-adding the connector in Settings → Connectors

ChatGPT doesn't use the tools

• Confirm Developer Mode is enabled (Settings → Apps & Connectors → Advanced settings)
• Check that the connector is active for your current conversation in the tools/apps panel
• Be explicit: "Use the [tool_name] tool to [do thing]." ChatGPT often needs direct tool references the first few times.

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), 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 (Extension 1)
• Home Maintenance Tracker (Extension 2)
• Family Calendar (Extension 3)
• Meal Planning (Extension 4)
• Professional CRM (Extension 5)
• Job Hunt Pipeline (Extension 6)

Every extension that deploys a remote MCP server uses this connection pattern.