Gbrain Http Wrapper

gbrain-http-wrapper

OAuth 2.1 + Bearer HTTP front-end for `gbrain serve` (stdio MCP). Lets non-stdio clients — **ChatGPT**, **Claude.ai web**, **Codex CLI** (remote), **Claude Desktop**, Perplexity, custom apps — read and write to the same GBrain backend that local clients use via stdio.

**Status:** Production. 7 clients connected: Claude Code CLI ✅, claude.ai web ✅, ChatGPT App (OAuth) ✅, Codex CLI (EC2 + Mac) ✅, OpenClaw/Telegram ✅, Hermes ✅

When to use this wrapper vs `gbrain serve --http`

GBrain v0.22.7+ ships `gbrain serve --http` natively. Use **this wrapper** when you need:

• OAuth 2.1 with PKCE + Dynamic Client Registration (ChatGPT requires this)
• Master password consent gate for third-party clients
• Process pool (N pre-warmed gbrain serve children for concurrency)
• Per-token rate limiting and audit logging
• Anti prompt-injection content wrapping
• Custom Instructions endpoint (/.well-known/mcp/custom-instructions)

Use **native `gbrain serve --http`** when you just need simple Bearer token auth for trusted clients.

Architecture

HTTP client (OAuth 2.1 or static Bearer)
   │
   ▼ POST /mcp { jsonrpc: "2.0", method: "tools/call", ... }
this server (Bun + Hono :8787)
   ├─ /.well-known/* + /oauth/* — OAuth 2.1 (PKCE + DCR + refresh)
   ├─ validates Bearer against access_tokens table
   ├─ routes JSON-RPC to one of N pre-warm `gbrain serve` children
   ├─ pipes the response back as JSON
   └─ /mcp/sse for SSE streaming clients
   │
   ▼ stdin/stdout
gbrain serve (stdio MCP)
   │
   ▼ DATABASE_URL
Supabase Postgres (the brain)

Tailscale Funnel mounts the wrapper at `/mcp` and **strips that prefix** before forwarding to the upstream. The wrapper therefore dual-mounts every route under both `/` and `/mcp` so that `https://your-machine.ts.net/mcp/...` works whether the prefix survives or not.

Endpoints

MCP (JSON-RPC over HTTP)

Method	Path	Auth	Purpose
GET	/health