Remote MCP

Phase 3 — Choose the client flow and owner authority

Use the successful expose receipt's mcp_url and admin_token_file; substitute them for the example URL/default path below, including when GBRAIN_HOME is customized. Run owner commands on the host or in a separately authorized admin harness with that server's protected credential. An ordinary connecting client hands these steps to that administrator; its OAuth scopes cannot grant owner authority. Follow mcp-access and MCP administration for owner actions and recovery.

To open the dashboard:

gbrain mcp admin login-link --url https://your-machine.your-tailnet.ts.net/mcp \
  --admin-token-file ~/.gbrain/serve/admin-token --json

Deliver the single-use link privately without fetching it. The plain admin URL does not authenticate. For pending native consent, add --oauth-request ID with the exact opaque ID from the client's browser request; the owner then reviews consent separately. Expired requests or a restart require restarting authorization in the native client.

For native OAuth, obtain the actual redirect URI and authentication method from the intended harness. CLIENT_REDIRECT_URI below must be replaced with that exact URI; it is not a suggested callback:

gbrain mcp admin register native-example --redirect-uri 'CLIENT_REDIRECT_URI' \
  --token-endpoint-auth-method none --profile memory-writer --source default \
  --url https://your-machine.your-tailnet.ts.net/mcp \
  --admin-token-file ~/.gbrain/serve/admin-token --dry-run --json

Review the preview, then repeat without --dry-run. For confidential PKCE, use the client's actual POST/Basic method and add --credentials-out PRIVATE_FILE before creation. Native registration creates authorization-code and refresh grants, not a machine token. Retrieve instructions using its returned ID:

gbrain mcp admin setup CLIENT_ID --harness generic --flow authorization-code \
  --url https://your-machine.your-tailnet.ts.net/mcp \
  --admin-token-file ~/.gbrain/serve/admin-token --json

Use the actual supported adapter ID when known; generic gives manual native settings instructions. The native client initiates OAuth and owns its verifier. An OAuthClientSetup is not a machine handoff for gbrain connect or gbrain mcp verify. Keep DCR off unless the owner explicitly chooses it; manual owner registration works without --enable-dcr.

For a client using a private machine handoff, preview through the same running server's admin API:

gbrain mcp grant agent-example --harness grok-bot --profile memory-writer \
  --source default \
  --url https://your-machine.your-tailnet.ts.net/mcp \
  --admin-token-file ~/.gbrain/serve/admin-token \
  --credentials-out /private/agent-example.json --dry-run --json

• --harness is the real adapter id (gbrain mcp adapters): grok-bot, muse, claude-desktop, codex, claude-code, opencode, ...
• Review the preview, then repeat without --dry-run to create the client.
• Profiles (memory-reader, memory-writer, coding-agent, operator, delegating-agent, full) and delegation limits are defined in hosted harness access; default to memory-writer, or memory-reader when only reading is requested.
• The receipt is redacted; the credentials file is 0600. Move it to the client through a private channel, never through the chat.

Phase 4 — Configure the selected connection inside the client

Tailnet-only endpoints are reachable only from devices signed in to the same tailnet — if a device cannot resolve your-machine.your-tailnet.ts.net, install Tailscale there and sign in; do not switch to --funnel for that.

Phase 5 — Verify

For the private machine path, from the client's environment:

gbrain mcp verify --client CLIENT_ID --harness grok-bot \
  --url https://your-machine.your-tailnet.ts.net/mcp \
  --credentials-file /private/agent-example.json --json

server_status: "passed" proves the permitted server checks; writable grants also exercise randomized write/readback and cleanup. Native activation remains separate; exit 2 (partial) is not completed native verification.

For native OAuth, observe gbrain://capabilities and an allowed call through that harness's authenticated MCP connection. Do not pass an OAuth setup export to the private-handoff verifier. For either path, observe calls in the intended harness and inspect the advertised schemas before a memory test. With an authorized writable grant, use only a harmless synthetic fact with provenance and explicit visibility: "world" within its source grant; retain its returned ID, verify recall in a new conversation, correct it, and withdraw it. Private facts cannot be recalled or withdrawn through these remote operations; never change real private content to pass a test. With read-only access, observe an authenticated read without adding write authority. Report registration, setup delivery, server checks, native calls, and cleanup separately.

Host-side check at any time: gbrain mcp expose --status (without a receipt it reports leftovers as leftovers_without_receipt, exit 1, with the exact cleanup command). Remove the exposure and host service: gbrain mcp expose --remove (stops and removes the service — also when the receipt says it was skipped but the unit exists — clears only gbrain's serve/funnel handler with --https=443 --set-path=/ off, keeps Tailscale installed and signed in — the Linux operator preference too — and keeps the admin token unless --force; without a receipt — an interrupted publish — it recovers from what is on disk: the wrapper, the unit and the :443 handler for --port, default 3131, leaving the token; the handler is turned off only when the wrapper, unit or service corroborates it — a handler standing alone is reported and left until --force). A handler that survives the off is never reported as removed: exit 1 handler_not_removed, receipt + wrapper kept for the re-run. An unreadable tailscale serve status stops both paths with exit 1 tailscale_serve_status_unreadable (the service is already removed; receipt and/or wrapper kept) — fix Tailscale, re-run the printed command. Declining the prompt exits 2 with "Nothing changed."; a --no-service re-run keeps an existing service.

Removing exposure does not revoke client registrations or erase brain data. Use the owner lifecycle commands in MCP administration to invalidate tokens, revoke, or delete a selected client after reviewing its consequences and revision.

PGLite single-writer note

While the exposed server runs, it holds the PGLite lock. Host-side commands that open the database (gbrain doctor, gbrain mcp grant WITHOUT an owner file or protected GBRAIN_ADMIN_BOOTSTRAP_TOKEN, gbrain bootstrap harness without --token) FAIL FAST with live_serve — they do not wait. Administer through the running server instead. gbrain sync and gbrain sweep --once are the exceptions: they delegate into the live serve automatically. Always provision through --admin-token-file; if the user needs concurrent local commands, route to postgres-adopt rather than stopping the server.

When it fails

Follow the agent operator protocol for any gbrain error code, exit code, [AGENT] block or notice block. Specific to this skill:

• gbrain mcp expose --status reports not_exposed (exit 2) or pending: wait for the certificate or service as the status says; leftovers_without_receipt (exit 1) means an interrupted run, so follow its fix.
• Installing Tailscale or a service needs the user's agreement before --yes; gbrain mcp expose still exits 2 when it needs confirmation (documented legacy), so read the block, not just the exit code.
• A client gets invalid_token / insufficient_scope: issue a scoped grant for that client; never hand out an admin credential to make it connect.

Anti-Patterns

• NEVER recommend ngrok or a cloud host first; Tailscale is the default and the alternatives are for people who explicitly want them.
• NEVER gbrain serve --http --bind 0.0.0.0 for this shape. Tailscale Serve terminates TLS and forwards to loopback; the default bind is correct.
• NEVER pass --funnel silently. Say that it makes the endpoint publicly reachable and why this client needs it.
• NEVER paste the admin token or a credentials file into the conversation, a commit, or a command argument the harness logs.
• NEVER run tailscale serve reset, tailscale logout, or uninstall Tailscale to clean up — gbrain mcp expose --remove touches only gbrain's handler.
• NEVER grant operator/full/admin because a health check failed.
• NEVER treat OAuth admin scope as owner authority, or install a native OAuth setup file as a private machine handoff.
• NEVER claim the client is connected because mcp verify passed; native activation and new-conversation recall are observed in the client.
• NEVER open the live PGLite database from a second process to provision.

Output Format

Report the host state and one line per client:

MCP URL   https://your-machine.your-tailnet.ts.net/mcp   (reach: tailnet only | public via Funnel)
Service   launchd com.gbrain.serve, running   (log: ~/.gbrain/serve/serve.log)
Engine    pglite — provision via --admin-token-file
Client    agent-example (grok-bot, memory-writer): granted, installed, verify passed, native activation pending
Pending   <exact next command, or "nothing">

Quote gbrain mcp expose --status and gbrain mcp verify output as-is (both are redacted). Name every unverified step explicitly; a passing server check never stands in for observed recall inside the client.