mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-27 22:15:33 +00:00
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>
This commit is contained in:
Garry Tan
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
8f063ce10c
commit
abf174b9ec
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user