diff --git a/docs/mcp/ALTERNATIVES.md b/docs/mcp/ALTERNATIVES.md
new file mode 100644
index 000000000..a889176d9
--- /dev/null
+++ b/docs/mcp/ALTERNATIVES.md
@@ -0,0 +1,54 @@
+# Alternative: Self-Hosted MCP Server
+
+If you prefer running GBrain on your own machine instead of Supabase Edge Functions, you can expose `gbrain serve --http` via a tunnel.
+
+## Tailscale Funnel
+
+[Tailscale Funnel](https://tailscale.com/kb/1223/tailscale-funnel) gives you a permanent public HTTPS URL with automatic TLS. Free tier available.
+
+```bash
+# 1. Install Tailscale
+brew install tailscale
+
+# 2. Start gbrain with HTTP transport (when available)
+gbrain serve --http 3000
+
+# 3. Expose via Funnel
+tailscale funnel 3000
+# Your brain is now at https://your-machine.ts.net
+```
+
+Pros: zero deployment, no Deno bundling, no cold start, no timeout limits.
+Cons: requires your machine to be running and connected.
+
+## ngrok
+
+[ngrok](https://ngrok.com) provides temporary or persistent tunnels.
+
+```bash
+# 1. Install ngrok
+brew install ngrok
+
+# 2. Start gbrain with HTTP transport
+gbrain serve --http 3000
+
+# 3. Expose via ngrok
+ngrok http 3000
+# Use the generated URL in your MCP client config
+```
+
+Pros: quick setup, works behind firewalls.
+Cons: free tier URLs change on restart (paid tier for persistent URLs), requires running process.
+
+## When to use alternatives vs Edge Functions
+
+| | Edge Functions | Tailscale/ngrok |
+|--|---|---|
+| Works when laptop is off | Yes | No |
+| Zero cold start | No (~300ms) | Yes |
+| No timeout limits | No (60s) | Yes |
+| sync_brain remotely | No | Yes |
+| file_upload remotely | No | Yes |
+| Extra accounts needed | None | Tailscale or ngrok |
+
+Note: `gbrain serve --http` is planned but not yet implemented. Currently only stdio transport is available via `gbrain serve`.
diff --git a/docs/mcp/CHATGPT.md b/docs/mcp/CHATGPT.md
new file mode 100644
index 000000000..83a5fba9c
--- /dev/null
+++ b/docs/mcp/CHATGPT.md
@@ -0,0 +1,25 @@
+# Connect GBrain to ChatGPT
+
+**Status: Coming Soon**
+
+ChatGPT requires OAuth 2.1 with Dynamic Client Registration for MCP connectors. Bearer token authentication is not supported by ChatGPT's MCP integration.
+
+This is tracked as a P0 priority for GBrain v0.7.
+
+## What's needed
+
+- OAuth 2.1 authorization endpoint on the Edge Function
+- Token endpoint with PKCE flow
+- Dynamic Client Registration support
+- ChatGPT Developer Mode (available on Pro/Team/Enterprise/Edu plans)
+
+## Workaround
+
+Until OAuth support ships, you can use GBrain with ChatGPT via a bridge:
+
+1. Run `gbrain serve` locally
+2. Use a tool like [mcp-remote](https://github.com/nichochar/mcp-remote) to bridge stdio to HTTP with OAuth support
+
+## Timeline
+
+Follow [Issue #22](https://github.com/garrytan/gbrain/issues/22) for updates on ChatGPT OAuth support.
diff --git a/docs/mcp/CLAUDE_CODE.md b/docs/mcp/CLAUDE_CODE.md
new file mode 100644
index 000000000..9c904415c
--- /dev/null
+++ b/docs/mcp/CLAUDE_CODE.md
@@ -0,0 +1,27 @@
+# Connect GBrain to Claude Code
+
+## Setup
+
+```bash
+claude mcp add gbrain -t http \
+  https://YOUR_REF.supabase.co/functions/v1/gbrain-mcp/mcp \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+Replace `YOUR_REF` with your Supabase project ref and `YOUR_TOKEN` with a token from `bun run src/commands/auth.ts create "claude-code"`.
+
+## Verify
+
+In Claude Code, try:
+
+```
+search for [any topic in your brain]
+```
+
+You should see results from your GBrain knowledge base.
+
+## Remove
+
+```bash
+claude mcp remove gbrain
+```
diff --git a/docs/mcp/CLAUDE_COWORK.md b/docs/mcp/CLAUDE_COWORK.md
new file mode 100644
index 000000000..18488e47f
--- /dev/null
+++ b/docs/mcp/CLAUDE_COWORK.md
@@ -0,0 +1,28 @@
+# Connect GBrain to Claude Cowork
+
+Two ways to get GBrain into Cowork sessions:
+
+## Option 1: Remote (via Edge Function)
+
+For Team/Enterprise plans, an org Owner adds the connector:
+
+1. Go to **Organization Settings > Connectors**
+2. Add a new connector with the MCP server URL:
+   ```
+   https://YOUR_REF.supabase.co/functions/v1/gbrain-mcp/mcp
+   ```
+3. Optionally add Bearer token authentication in Advanced Settings
+4. Save
+
+Note: Cowork connects from Anthropic's cloud, not your device. The Edge Function is already publicly reachable via Supabase.
+
+## Option 2: Local Bridge (via Claude Desktop)
+
+If you already have GBrain configured in Claude Desktop (either via `gbrain serve` stdio or the remote MCP integration), Cowork gets access automatically. Claude Desktop bridges local MCP servers into Cowork via its SDK layer.
+
+This means: if `gbrain serve` is running and configured in Claude Desktop, you don't need the Edge Function for Cowork at all.
+
+## Which to use?
+
+- **Remote Edge Function:** works even when your laptop is closed, available to all org members
+- **Local Bridge:** zero extra setup if Claude Desktop already has GBrain, but requires your machine to be running
diff --git a/docs/mcp/CLAUDE_DESKTOP.md b/docs/mcp/CLAUDE_DESKTOP.md
new file mode 100644
index 000000000..da07f374b
--- /dev/null
+++ b/docs/mcp/CLAUDE_DESKTOP.md
@@ -0,0 +1,31 @@
+# Connect GBrain to Claude Desktop
+
+**Important:** Claude Desktop does NOT connect to remote MCP servers via `claude_desktop_config.json`. That file only works for local stdio servers. Remote HTTP servers must be added through the GUI.
+
+## Setup
+
+1. Open Claude Desktop
+2. Go to **Settings > Integrations**
+3. Click **Add Integration** (or **Add Connector**)
+4. Enter the MCP server URL:
+   ```
+   https://YOUR_REF.supabase.co/functions/v1/gbrain-mcp/mcp
+   ```
+5. Set authentication to **Bearer Token** and paste your token
+6. Save
+
+## Verify
+
+Start a new conversation and try:
+
+```
+Search my brain for [any topic]
+```
+
+Claude Desktop will use your GBrain tools automatically.
+
+## Common Mistakes
+
+**Using claude_desktop_config.json for remote servers** — this silently fails. The JSON config only works for local stdio MCP servers. Remote HTTP servers must be added via Settings > Integrations.
+
+**Using the wrong URL** — make sure the URL ends with `/mcp` (not `/health` or just the function name).
diff --git a/docs/mcp/DEPLOY.md b/docs/mcp/DEPLOY.md
new file mode 100644
index 000000000..28c536d41
--- /dev/null
+++ b/docs/mcp/DEPLOY.md
@@ -0,0 +1,102 @@
+# Deploy GBrain Remote MCP Server
+
+Deploy your personal knowledge brain as a serverless MCP endpoint on your existing Supabase instance. Works with Claude Desktop, Claude Code, Cowork, and Perplexity Computer.
+
+## Prerequisites
+
+- GBrain already set up (`gbrain init` completed, data imported)
+- [Supabase CLI](https://supabase.com/docs/guides/cli) installed
+- Your Supabase project ref (the `xxx` from `https://xxx.supabase.co`)
+
+## Quick Start
+
+```bash
+# 1. Fill in your config
+cp .env.production.example .env.production
+# Edit .env.production with your DATABASE_URL, OPENAI_API_KEY, SUPABASE_PROJECT_REF
+
+# 2. Deploy (one command)
+bash scripts/deploy-remote.sh
+
+# 3. Create an access token
+DATABASE_URL=$DATABASE_URL bun run src/commands/auth.ts create "my-client"
+# Save the token — it's shown once
+
+# 4. Test it
+bun run src/commands/auth.ts test \
+  https://YOUR_REF.supabase.co/functions/v1/gbrain-mcp/mcp \
+  --token YOUR_TOKEN
+```
+
+## Authentication
+
+GBrain uses bearer tokens stored in your database (SHA-256 hashed). Each token has a name for identification.
+
+```bash
+# Create a token
+bun run src/commands/auth.ts create "claude-desktop"
+
+# List all tokens
+bun run src/commands/auth.ts list
+
+# Revoke a token
+bun run src/commands/auth.ts revoke "claude-desktop"
+```
+
+Tokens are per-client. Create one for each device/app. Revoke individually if compromised.
+
+## Updating
+
+When you update GBrain (new operations, bug fixes):
+
+```bash
+git pull
+bash scripts/deploy-remote.sh
+```
+
+Your tokens survive upgrades. Check your deployed version:
+
+```bash
+curl https://YOUR_REF.supabase.co/functions/v1/gbrain-mcp/health
+```
+
+## Operations
+
+All 28 GBrain operations are available remotely except:
+- `sync_brain` (may exceed 60s Edge Function timeout)
+- `file_upload` (may exceed 60s timeout with large files)
+
+These remain CLI-only via `gbrain serve` (stdio).
+
+## Troubleshooting
+
+**"supabase: command not found"**
+Install: `brew install supabase/tap/supabase` or `npm install -g supabase`
+
+**Edge Function deploys but returns 500**
+Check that OPENAI_API_KEY is set: `supabase secrets list`
+
+**"missing_auth" error**
+Include the Authorization header: `Authorization: Bearer YOUR_TOKEN`
+
+**"invalid_token" error**
+Run `bun run src/commands/auth.ts list` to see active tokens. The token may have been revoked or mistyped.
+
+**"service_unavailable" error**
+Database connection failed. Check your Supabase dashboard for outages or connection pool limits.
+
+**Claude Desktop doesn't connect**
+Remote MCP servers must be added via Settings > Integrations, NOT claude_desktop_config.json. See [CLAUDE_DESKTOP.md](CLAUDE_DESKTOP.md).
+
+## Expected Latencies
+
+| Operation | Typical Latency | Notes |
+|-----------|----------------|-------|
+| get_page | < 100ms | Single DB query |
+| list_pages | < 200ms | DB query with filters |
+| search (keyword) | 100-300ms | Full-text search |
+| query (hybrid) | 1-3s | Embedding + vector + keyword + RRF |
+| put_page | 100-500ms | Write + trigger search_vector update |
+| get_stats | < 100ms | Aggregate query |
+
+Cold start adds ~300-500ms on the first request after idle (Postgres connection setup via pgbouncer).
diff --git a/docs/mcp/PERPLEXITY.md b/docs/mcp/PERPLEXITY.md
new file mode 100644
index 000000000..5042e02f6
--- /dev/null
+++ b/docs/mcp/PERPLEXITY.md
@@ -0,0 +1,27 @@
+# Connect GBrain to Perplexity Computer
+
+Perplexity Computer supports remote MCP servers with bearer token authentication.
+
+## Setup
+
+1. Open Perplexity (requires Pro subscription)
+2. Go to **Settings > Connectors** (or **MCP Servers**)
+3. Add a new remote connector:
+   - **URL:** `https://YOUR_REF.supabase.co/functions/v1/gbrain-mcp/mcp`
+   - **Authentication:** API Key / Bearer Token
+   - **Token:** your GBrain access token
+4. Save
+
+## Verify
+
+In a Perplexity conversation, ask it to use your brain:
+
+```
+Use my GBrain to search for [topic]
+```
+
+## Notes
+
+- Perplexity Computer is available to Pro subscribers
+- Both the Perplexity Mac app and web version support MCP connectors
+- The Mac app also supports local MCP servers if you prefer `gbrain serve` (stdio)