Make the control plane usable before adding more autonomy.

What is connected, captured and autonomous?

Set up Open Brain on another machine in 5 minutes

Open Brain memory lives in one shared Postgres on Railway. Every device you connect sees the same brain — there is no syncing to wait for. Pick the AI app you want to connect below, follow the steps, and the same memory you have here will be available there.

"Couldn't reach the MCP server" — fix Cloudflare Access

If you self-host Open Brain behind Cloudflare Access (email-gated zero-trust), MCP connectors cannot reach /mcp. Every request is 302-redirected to a Cloudflare login page before it touches your server, and the connector expects JSON-RPC. The reliable fix is to expose /mcp on a dedicated subdomain that is not enrolled in any Access app — your MCP route already ships its own OAuth 2.1 (PKCE + dynamic client registration + setup-code approval), so this loses zero security. CF Access was duplicative auth for an endpoint that isn't a browser surface; connectors can't follow its email-link login flow anyway.

curl -i -X POST https://your-domain/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}'

Phase 1 — Pick a connector setup code

When CF Access is not in front of the request, /oauth/authorize falls back to a "Connector setup code" prompt. Without the env var below set, every code is rejected and the OAuth flow can't complete.

1. Generate a long random string

   PowerShell: -join ((1..32) | %{ [char]((48..57)+(65..90)+(97..122) | Get-Random) }). Or use any password manager — 32+ chars, alphanumeric. Save it; you'll paste it once per connecting device.
2. Add it to Railway as MCP_OAUTH_SETUP_CODE

   Railway dashboard → your Open Brain project → server service → Variables tab → New Variable. Name MCP_OAUTH_SETUP_CODE, value = the random string. Save.
3. Wait for the redeploy

   Railway redeploys automatically (~30–60s). Watch the deploy log until you see Server listening.

Phase 2 — Add a CNAME in Cloudflare DNS

1. Open the Cloudflare DNS panel

   dash.cloudflare.com → select your zone → DNS → Records → Add record.
2. Create the CNAME

   Type: CNAME. Name: mcp (just the subdomain — Cloudflare appends the zone). Target: your existing Railway custom-domain target (find it in Railway → Project → Settings → Networking — same target as your apex domain uses). Proxy status: Proxied (orange cloud ON) — required for TLS. TTL: Auto.
3. Verify DNS

   From any shell: nslookup mcp.your-domain. Cloudflare DNS propagates within seconds.

Phase 3 — Add the custom domain on Railway

1. Open Railway's domain panel

   Railway → your project → click the Open Brain server service → Settings tab → scroll to Networking / Domains.
2. Add the custom domain

   + Custom Domain → enter mcp.your-domain → Add Domain. Railway probes DNS and provisions a TLS cert automatically.
3. Wait for "Active" status

   Usually 15–90 seconds. If still pending after 5 min, hard-refresh the Railway page — its UI sometimes caches stale state.
4. Quick browser test

   Open https://mcp.your-domain/health. A JSON 401 (or similar from auth middleware) means TLS works and CF Access is not in the way. A Cloudflare login page means Phase 4 still has work to do.

Phase 4 — Confirm Cloudflare Access doesn't catch the new subdomain

1. Audit your Access applications

   Top-right account menu → Zero Trust → Access → Applications. Inspect each app's Application domain column.
2. Make sure none of them catches mcp.your-domain

   If you see a wildcard like *.your-domain, the new subdomain is re-gated. Three fixes — pick one:

   • Narrow that app's domain to just the apex (your-domain) plus any specific subdomains you do want gated.
   • In the same app, replace the wildcard with one explicit domain row per gated host.
   • Create a new Access app scoped to mcp.your-domain/* with a single Action: Bypass, Include: Everyone policy. Bypass apps short-circuit any wildcard parent.
3. Smoke-test again

   Re-run the curl probe at the top of this article against https://mcp.your-domain/mcp. Pass = HTTP/1.1 401 with WWW-Authenticate: Bearer …. Fail = HTTP/1.1 302 with Location: …cloudflareaccess.com. If still 302, the audit missed something — re-check.

Phase 5 — Connect from Claude.ai

1. Open Claude's connector settings

   claude.ai → your avatar (top-right) → Settings → Connectors (or Integrations depending on plan).
2. Add a custom connector

   Name: Open Brain. URL: https://mcp.your-domain/mcp. Click Add / Connect.
3. Approve the OAuth flow

   A popup opens. You should see an Open Brain-branded "Approve Claude connector" page asking for a Connector setup code. If you see a Cloudflare login page instead → Phase 4 failed; go back. Paste the value of MCP_OAUTH_SETUP_CODE from Phase 1. Click Approve Claude connector.
4. Enable it in a chat

   Open any Claude conversation → click the connector icon → toggle Open Brain ON. Send a test message like "Search my Open Brain for X". A successful tool call confirms end-to-end.

Phase 6 — (optional) Make this setup page advertise the new URL

The MCP URL in the snippets above is derived from whichever host you load this page from. If you usually open this page at the (still-gated) apex, the displayed URL won't match the working MCP subdomain. Two ways to fix:

1. Page-level override (simplest, no redeploy)

   Edit server/public/setup.html. In <head> find <meta name="ob-public-mcp-url" content=""> and set content="https://mcp.your-domain/mcp". All connector snippets on this page (Claude Code, Claude Desktop, Cursor, Claude.ai, ChatGPT) will use it. Commit and push.
2. Server-wide override

   Set PUBLIC_BASE_URL=https://mcp.your-domain in Railway env. This makes OAuth metadata and other server-generated URLs advertise the MCP subdomain. (The setup-page snippets above are rendered client-side, so you still want the meta tag too.)

Disconnect a client or kill a permanent token

Every OAuth handshake mints a row in api_keys named Remote MCP OAuth <client> (claude|chatgpt|unknown). Deleting that row revokes the token instantly — the next request from that client gets a 401 and the connection drops. Use this when you suspect a token leaked, when a client is stuck in a bad state, or when retiring a device.

DELETE FROM api_keys
WHERE name LIKE 'Remote MCP OAuth%(claude)%';

DELETE FROM api_keys
WHERE name LIKE 'Remote MCP OAuth%';

SELECT name, created_at, last_used_at,
       COALESCE(expires_at::text, 'never') AS expires
FROM api_keys
WHERE name LIKE 'Remote MCP OAuth%'
ORDER BY created_at DESC;

Fix these first