91ced664b6
* chore: remove Supabase Edge Function MCP deployment The Edge Function never worked reliably. All MCP traffic goes through self-hosted server + ngrok tunnel. Removes deploy-remote.sh, edge-entry.ts, supabase/functions/, .env.production.example, and CHATGPT.md (OAuth not implemented). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: rewrite MCP docs for self-hosted + ngrok deployment All per-client guides updated from Edge Function URLs to self-hosted server + ngrok tunnel pattern. DEPLOY.md rewritten with local vs remote paths. ALTERNATIVES.md now shows self-hosted as primary, with ngrok, Tailscale, and Fly.io/Railway comparison. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: voice recipe v0.8.0 — 25 production patterns from real deployment Identity separation, pre-computed bid system, conversation timing fix, proactive advisor mode, radical prompt compression, OpenAI Realtime Prompting Guide structure, auth-before-speech, brain escalation, stuck watchdog, never-hang-up rule, thinking sounds, fallback TwiML, tool set architecture, trusted user auth, caller routing, dynamic VAD, on-screen debug UI, live moment capture, belt-and-suspenders post-call, mandatory 3-step post-call, WebRTC parity, dual API events, report-aware query routing. WebRTC pseudocode updated with native FormData and 6 gotchas. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: post-upgrade feature discovery framework upgrade.ts captures old version before upgrading, then execs gbrain post-upgrade (new binary) to read migration files and print feature pitches. Migration files get YAML frontmatter with feature_pitch field (headline, description, recipe, tiers). CLI prints excited builder tone post-upgrade. v0.8.0 migration offers voice setup with environment detection (server vs local) and 3-tier progressive disclosure. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: add Voice section to README with WebRTC screenshot + tweet link Her out of the box: voice-to-brain with 25 production patterns. WebRTC client screenshot embedded. Remote MCP section rewritten for self-hosted + ngrok. Setup block genericized. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * test: add recipe validation tests + genericize personal refs 5 new integration tests: secrets completeness, semver version, requires resolution, all-recipes-parse, no-personal-references. Test fixture genericized. CLAUDE.md/TODOS.md/SKILLPACK updated for v0.8.0. build:edge script removed from package.json. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v0.8.0) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
116 lines
3.3 KiB
Markdown
116 lines
3.3 KiB
Markdown
# Deploy GBrain Remote MCP Server
|
|
|
|
Access your brain from any device, any AI client. GBrain's MCP server runs locally
|
|
via `gbrain serve` (stdio). For remote access, wrap it in an HTTP server behind a
|
|
public tunnel.
|
|
|
|
## Two Paths
|
|
|
|
### Local (zero setup)
|
|
|
|
```bash
|
|
gbrain serve
|
|
```
|
|
|
|
Works with Claude Code, Cursor, Windsurf, and any MCP client that supports stdio.
|
|
No server, no tunnel, no token needed.
|
|
|
|
### Remote (any device, any AI client)
|
|
|
|
```
|
|
Your AI client (Claude Desktop, Perplexity, etc.)
|
|
→ ngrok tunnel (https://YOUR-DOMAIN.ngrok.app)
|
|
→ Your HTTP server (wraps gbrain serve)
|
|
→ Supabase Postgres (via pooler connection string)
|
|
```
|
|
|
|
This requires:
|
|
1. A machine running `gbrain serve` behind an HTTP wrapper
|
|
2. A public tunnel (ngrok, Tailscale, or cloud host)
|
|
3. Bearer token auth for security
|
|
|
|
## Remote Setup
|
|
|
|
### 1. Set up the tunnel
|
|
|
|
See the [ngrok-tunnel recipe](../../recipes/ngrok-tunnel.md) for full setup.
|
|
Quick version:
|
|
|
|
```bash
|
|
brew install ngrok
|
|
ngrok config add-authtoken YOUR_TOKEN
|
|
ngrok http 8787 --url your-brain.ngrok.app # Hobby tier for fixed domain
|
|
```
|
|
|
|
### 2. Create access tokens
|
|
|
|
```bash
|
|
# Create a token for each client
|
|
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. Tokens are stored SHA-256 hashed in your database.
|
|
|
|
### 3. Connect your AI client
|
|
|
|
- **Claude Code:** [setup guide](CLAUDE_CODE.md)
|
|
- **Claude Desktop:** [setup guide](CLAUDE_DESKTOP.md) (must use GUI, not JSON config)
|
|
- **Claude Cowork:** [setup guide](CLAUDE_COWORK.md)
|
|
- **Perplexity:** [setup guide](PERPLEXITY.md)
|
|
|
|
### 4. Verify
|
|
|
|
```bash
|
|
bun run src/commands/auth.ts test \
|
|
https://YOUR-DOMAIN.ngrok.app/mcp \
|
|
--token YOUR_TOKEN
|
|
```
|
|
|
|
## Operations
|
|
|
|
All 30 GBrain operations are available remotely, including `sync_brain` and
|
|
`file_upload` (no timeout limits with self-hosted server).
|
|
|
|
## Deployment Options
|
|
|
|
See [ALTERNATIVES.md](ALTERNATIVES.md) for a comparison of ngrok, Tailscale
|
|
Funnel, and cloud hosts (Fly.io, Railway).
|
|
|
|
## Troubleshooting
|
|
|
|
**"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.
|
|
|
|
**"service_unavailable" error**
|
|
Database connection failed. Check your Supabase dashboard for outages.
|
|
|
|
**Claude Desktop doesn't connect**
|
|
Remote 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 |
|
|
|
|
**Note:** `gbrain serve --http` (built-in HTTP transport) is planned but not yet
|
|
implemented. Currently, remote MCP requires a custom HTTP wrapper. See the
|
|
production deployment pattern in the [voice recipe](../../recipes/twilio-voice-brain.md)
|
|
for a reference implementation.
|