Files

Garry Tan abf174b9ec docs: per-client MCP setup guides

- docs/mcp/DEPLOY.md — deployment walkthrough, auth, troubleshooting, latency table
- docs/mcp/CLAUDE_CODE.md — claude mcp add command
- docs/mcp/CLAUDE_DESKTOP.md — Settings > Integrations (NOT JSON config!)
- docs/mcp/CLAUDE_COWORK.md — remote + local bridge paths
- docs/mcp/PERPLEXITY.md — Perplexity Computer connector setup
- docs/mcp/CHATGPT.md — coming soon (requires OAuth 2.1, P0 TODO)
- docs/mcp/ALTERNATIVES.md — Tailscale Funnel + ngrok self-hosted options

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-10 08:01:56 -10:00

3.1 KiB

Raw Blame History

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 installed
Your Supabase project ref (the xxx from https://xxx.supabase.co)

Quick Start

# 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.

# 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):

git pull
bash scripts/deploy-remote.sh

Your tokens survive upgrades. Check your deployed version:

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.

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).

3.1 KiB Raw Blame History