/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 register one least-privilege client per consumer, choose
  native OAuth/PKCE or a private machine handoff for that client, and verify
  the connection inside the intended harness.
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

the receipt's `admin_token_file` (normally `~/.gbrain/serve/admin-token`); machine and confidential OAuth credentials land in a private `--credentials-out` file. Public PKCE has no secret. Quote redacted receipts; deliver a requested owner login link privately and unopened.

• **Owner authority is separate.** The expose-managed wrapper loads its

token file as `GBRAIN_ADMIN_BOOTSTRAP_TOKEN`; that file authorizes `gbrain mcp admin` and `mcp grant` against that server. An ordinary MCP token, client secret, or OAuth `admin` scope does not. With `--no-service`, use the independently running server's actual configured owner credential; creating an expose token file does not configure that process.

• **Least privilege.** One client per consumer, `memory-writer` for ordinary

memory use or `memory-reader` for read-only access. Broader access requires the user's request. Never `operator` / `full` / `admin` to make a convenience check pass.

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

private machine handoff and checks the access that grant permits. Native OAuth is verified through the native client's authenticated connection. A generated file or server probe does not prove that client loaded its tools.

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](https://github.com/garrytan/gbrain/blob/master/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.

Network reach and authentication are separate choices. A vendor name or tailnet/Funnel mode does not select the credential flow: inspect the intended clien