/remote-mcp

name: remote-mcp
description: |
  Publish the user's own gbrain over MCP so other devices, desktop apps and
  cloud agents can reach it. `gbrain mcp expose` installs and signs in
  Tailscale, publishes the running `gbrain serve --http` on the tailnet
  (HTTPS, tailnet-only by default; Funnel only when a client lives in a
  vendor cloud), keeps the server alive as a user service, and hands back the
  MCP URL. Then grant one least-privilege client per consumer, install the
  handoff inside that client, and verify a real memory round trip.
triggers:
  - "use my brain over mcp"
  - "serve my brain over mcp"
  - "expose my brain over mcp"
  - "gbrain mcp server"
  - "remote mcp access to my brain"
  - "put my brain on tailscale"
  - "connect grok bot to my brain"
  - "connect muse to my brain"
  - "connect claude desktop to my brain"
  - "reach my brain from my phone"
  - "gbrain mcp expose"
tools:
  - exec
mutating: true
# exempt: this skill changes host networking/service state and never answers
# a knowledge question, so there is nothing to look up in the brain first.
brain_first: exempt

Remote MCP — use your brain from anywhere

> The brain already runs on the user's computer. This skill makes it reachable > over MCP from their other devices and from the agents they use elsewhere, > without moving the data and without putting a database on the public > internet. Tailscale is the default transport; publishing is one command, > access is one scoped grant per client.

Contract

This skill guarantees:

• **Tailscale by default.** `gbrain mcp expose` publishes the local server

with `tailscale serve` (HTTPS on the tailnet, nothing public). ngrok and cloud hosts stay documented alternatives, never the first suggestion.

• **Funnel is explicit.** Cloud agents whose runtime is not on the tailnet

(Grok Bot, Muse, ChatGPT, Claude.ai / Cowork, Perplexity) need `--funnel`, which makes the same `*.ts.net` name publicly reachable. Say so before running it; the endpoint is then protected by gbrain's OAuth / bearer auth and scoped grants, not by the network.

• **Consent before system changes.** Installing Tailscale, running

`tailscale up`, writing a serve/funnel config and creating a user service are host-state changes. Show the operator the printed plan and get a yes before passing `--yes`.

• **Engine-free.** `gbrain mcp expose` never opens the database. On a PGLite

brain the running server owns the single-writer lock, so every later provisioning step goes through the server's authenticated admin API (`--admin-token-file`), never a second process on the database.

• **No secrets in chat.** The admin token lives in

`~/.gbrain/serve/admin-token`; client credentials land in a private `--credentials-out` file. Quote redacted receipts only.

• **Least privilege.** One client per consumer, `memory-writer` unless the

user explicitly asks for more. Never `operator` / `full` / `admin` to make a convenience check pass.

• **Server checks are not native activation.** `gbrain mcp verify` proves

transport, auth, permissions and a write/readback. Whether the client's own UI actually loaded the tool is a separate observation in that client.

Decision table — who is connecting?

| Client | Shape | Command | | --- | --- | --- | | Your own devices: Claude Desktop, Claude Code / Codex / opencode on another laptop, phone apps joined to the tailnet | tailnet-only HTTPS (default) | `gbrain mcp expose --dry-run` (preview; the run itself is Phase 2, after consent) | | Cloud agents running in a vendor's cloud: Grok Bot, Muse, ChatGPT connector, Claude.ai / Cowork, Perplexity Computer | public HTTPS on the same `*.ts.net` name | `gbrain mcp expose --funnel --dry-run` (preview; Phase 2 after consent) | | Cloud agent whose runtime you can join to your tailnet (userspace `tailscaled`, ephemeral auth key) | tailnet-only | Advanced, unverified, not automated — see the [remote MCP guide](../../docs/guides/remote-mcp.md) | | Local agents on the same machine (Claude Code, Codex, opencode) | loopback — no Tailscale needed | Postgres: `gbrain bootstrap harness --yes --port 3131`. PGLite: mint the token BEFORE the service runs (`gbrain auth create local-agents --scopes read,write` — before `gbrain mcp expose`, or while the service is briefly stopped) and pass `gbrain bootstrap harness --yes --port 3131 --token <value>`; OR use the scoped path `gbrain mcp grant <name> --harness <id> --profile memory-writer --source default --url http://127.0.0.1:3131/mcp --admin-token-file ~/.gbrain/serve/admin-token --credentials-out /private/<name>.json` then `gbrain connect http://127.0.0.1:3131/mcp --harness <id> --credentials-file /private/<name>.json --install` (MCP wiring only, no per-turn hooks) | | Thin client only (this machine has no brain) | — | Stop: run this skill on the brain host |

Grok Bot and Muse users with no always-on machine keep the in-agent local install described in [setup](../setup/SKILL.md) as the alternative.

Phase 1 — Detect

gbrain engine status --json
gbrain mcp expose --status --json

• `thin_client: true` → the brain lives elsewhere. Stop and say the command

runs on the brain host.

• `effective_engine: "pglite"` → note the single-writer rule (below) before

continuing; `"postgres"` → concurrent local commands stay fine.

• `--status` reports `status: "not_exposed"` (exit 2 with `--json`) →

Phase 2. `status: "exposed"` → skip to Phase 3 with the printed `mcp_url`. `status: "pending"` → the certificate or service is still coming up; re-run `--status` in a minute before changing anything. `reason: "leftovers_without_receipt"` (exit 1) → an interrupted run left the wrapper, the unit / service or a `:443` handler behind; run the exact `gbrain mcp expose --remove --yes …` line from `next_actions` (it carries `--force` only when a handler stands alone), then Phase 2.

• The brain is already reachable over HTTPS by other means (an existing

`serve --http