remote-mcp

远程 MCP — 随时随地使用你的大脑

大脑已经在用户的计算机上运行。此技能让用户能够通过 MCP，从其他设备以及他们在其他地方使用的 Agent 访问大脑， 无需迁移数据，也无需将数据库暴露到公共 互联网。默认使用 Tailscale 进行传输；发布只需一条命令， 每个客户端只需一次限定范围的授权即可访问。

约定

此技能保证：

• 默认使用 Tailscale。 gbrain mcp expose 使用 tailscale serve 发布本地服务 （在 tailnet 上通过 HTTPS 访问，不会暴露到公共网络）。ngrok 和 云主机仍会作为替代方案记录，但绝不会作为首选建议。
• 明确启用 Funnel。 运行环境不在 tailnet 上的云端 Agent（Grok Bot、Muse、ChatGPT、Claude.ai / Cowork、Perplexity）需要 使用 --funnel，这会让同一个 *.ts.net 域名可通过公共网络访问。运行前须说明这一点；此时端点依靠 gbrain 的 OAuth / bearer 身份验证和限定范围的授权保护，而非网络本身。
• 更改系统前征得同意。 安装 Tailscale、运行 tailscale up、写入 serve/funnel 配置以及创建用户服务都会更改主机状态。显示打印出的计划，并在传入 --yes 前征得操作者同意。
• 不访问引擎。 gbrain mcp expose 绝不会打开数据库。在 PGLite 大脑上，正在运行的服务持有唯一写入者锁，因此之后的每个配置步骤都必须通过服务的身份验证管理 API（--admin-token-file）执行，绝不能启动第二个进程访问数据库。
• 不在聊天中泄露密钥。 管理令牌保存在回执中的 admin_token_file（通常为 ~/.gbrain/serve/admin-token）； 机器凭据和机密 OAuth 凭据写入私有的 --credentials-out 文件。公共 PKCE 不含密钥。引用回执时应将敏感信息脱敏；如需提供所有者登录链接，应私下发送且不要打开。
• 所有者权限单独管理。 expose 管理的包装器会将其令牌文件加载为 GBRAIN_ADMIN_BOOTSTRAP_TOKEN；该文件用于针对该服务执行 gbrain mcp admin 和 mcp grant。普通 MCP 令牌、客户端密钥或 OAuth admin 作用域都不具备此权限。使用 --no-service 时，请使用独立运行的服务实际配置的所有者凭据；创建 expose 令牌文件并不会配置该进程。
• 遵循最小权限原则。 每个使用方使用一个客户端；普通记忆使用授予 memory-writer，只读访问授予 memory-reader。更广泛的访问权限须由用户提出。切勿为了通过便捷性检查而授予 operator / full / admin 权限。
• 服务端检查不等于原生激活。 gbrain mcp verify 接受私有机器交接，并检查授权允许的访问权限。原生 OAuth 通过原生客户端的已验证连接进行验证。生成文件或探测服务端都无法证明客户端已加载其工具。

决策表 — 谁要连接？

客户端	形式	命令
你自己的设备：Claude Desktop、另一台笔记本上的 Claude Code / Codex / opencode、已加入 tailnet 的手机应用	仅限 tailnet 的 HTTPS（默认）	gbrain mcp expose --dry-run（预览；实际运行属于 Phase 2，需先征得同意）
运行在供应商云端的云端 Agent：Grok Bot、Muse、ChatGPT connector、Claude.ai / Cowork、Perplexity Computer	使用相同 *.ts.net 名称的公共 HTTPS	gbrain mcp expose --funnel --dry-run（预览；征得同意后进入 Phase 2）
可将运行环境加入 tailnet 的云端 Agent（用户空间 tailscaled、临时身份验证密钥）	仅限 tailnet	高级用法，未经验证，未自动化 — 请参阅远程 MCP 指南
同一台机器上的本地 Agent（Claude Code、Codex、opencode）	回环地址 — 无需 Tailscale	Postgres：gbrain bootstrap harness --yes --port 3131。PGLite：在服务运行前创建令牌（运行 gbrain mcp expose 之前，或短暂停止服务时运行 gbrain auth create local-agents --scopes read,write），并传入 gbrain bootstrap harness --yes --port 3131 --token <value>；或者使用授权范围路径 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，然后运行 gbrain connect http://127.0.0.1:3131/mcp --harness <id> --credentials-file /private/<name>.json --install（仅配置 MCP 连接，不设置逐轮钩子）
仅使用轻量客户端（此机器没有 brain）	—	停止：在 brain 主机上运行此技能

没有常开机器的 Grok Bot 和 Muse 用户，可将 setup 中介绍的 Agent 内本地安装作为替代方案。

网络可达性和身份验证是两个独立的选择。供应商名称或 tailnet/Funnel 模式不会决定凭据流程：在 Phase 3 中检查目标客户端原生的 OAuth 设置或受支持的私密交接适配器。

Phase 1 — 检测

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

• thin_client: true → brain 位于其他位置。停止并说明该命令需在 brain 主机上运行。
• effective_engine: "pglite" → 继续前说明单写入者规则（见下文）；"postgres" → 并发本地命令仍可正常运行。
• --status 报告 status: "not_exposed"（使用 --json 时退出码为 2）→ 进入 Phase 2。status: "exposed" → 跳到 Phase 3，使用打印出的 mcp_url。status: "pending" → 证书或服务仍在启动；一分钟后重新运行 --status，再进行任何更改。 reason: "leftovers_without_receipt"（退出码为 1）→ 中断的运行留下了包装器、单元 / 服务或 :443 处理程序；运行 next_actions 中的确切 gbrain mcp expose --remove --yes … 命令（仅当处理程序独立存在时才会包含 --force），然后进入 Phase 2。
• brain 已通过其他方式经由 HTTPS 可访问（现有的、位于 ngrok / 反向代理之后的 serve --http，或托管在其他位置的 brain）→ 不要运行 gbrain mcp expose。直接进行托管访问：选择客户端的连接方式，并通过该端点注册（在 Phase 3 中提供其 URL 和所有者权限），然后配置客户端（Phase 4）。
• 询问哪些客户端需要访问 brain（由决策表决定使用 tailnet 还是 --funnel）。不要询问用户已经回答过的问题。

Phase 2 — 发布

先预览，再征得同意后运行：

gbrain mcp expose --dry-run            # prints the plan; changes nothing
gbrain mcp expose --yes                # your own devices (tailnet only)
gbrain mcp expose --funnel --yes       # a cloud agent must reach it

选项：--port N（默认值为 3131）、--surface verbs|starter|full（默认值为 full，与 serve --http 一致）、--enable-dcr、--no-tailscale（不发布任何内容；仅安装服务）、--no-service（仅发布；由操作员自行运行 serve）、--no-install（不安装 Tailscale，直接失败）、--force（接管已指向其他本地端口的服务处理程序）、--json。 命令的执行顺序：规划（若端口上已有任何监听程序——无论是否为 HTTP——且未指定 --no-service，则立即拒绝；若 --no-tailscale 遇到记录了活动 tailnet 映射的凭据回执，也会立即拒绝）→ 征求同意 → 查找或安装 tailscale 二进制文件 → 如有需要则登录（Linux：sudo tailscale set --operator=$USER，然后执行 sudo tailscale up——仅当前置的二进制文件是系统安装时才使用 sudo；操作员偏好设置会持久保存，--remove 不会撤销该设置；macOS：tailscale up）→ 读取设备的 tailnet DNS 名称，并预先检查 HTTPS 证书是否已启用（使用 --funnel 时，还会检查节点是否具备 Funnel 功能）→ 执行 tailscale serve / funnel → 确保管理员令牌可用 → 写入包装脚本和 launchd 代理 / systemd 用户单元 → 轮询本地及 tailnet /health → 写入回执 ~/.gbrain/serve/expose.json。使用 --json 时，每一步都会成为一个具名检查（plan、consent、tailscale.binary、tailscale.login、tailscale.identity、tailscale.publish、admin_token、service、verify.local、verify.tailnet、receipt）；健康检查是 verify.local 和 verify.tailnet，而不是 verify。

转达命令显示的每一条提示词：

输出	操作
tailscale up 打印的 Tailscale 登录 URL	将 URL 提供给用户，等待他们登录；若以退出码 2（tailscale_login_pending）退出，则重新运行输出中打印的确切命令
declined（退出码 2，“Nothing changed.”）	操作者在提示时选择了拒绝。未安装或发布任何内容；只有在他们确认打印出的计划后，才传入 --yes
tailscale_https_not_enabled — 预检查，退出码 2，未发布任何内容（CertDomains 为空）	在 https://login.tailscale.com/admin/dns 启用 MagicDNS + HTTPS Certificates，然后重新运行打印出的命令。若相同原因对应退出码 1，则表示 tailscale serve 调用本身因同一原因拒绝了操作，修复方法相同
tailscale_funnel_not_enabled — 预检查，退出码 2，未发布任何内容（节点缺少 Funnel 能力）	在 tailnet 策略中启用 funnel 节点属性（https://login.tailscale.com/admin/acls；参见 https://tailscale.com/kb/1223/funnel），然后重新运行。此原因对应退出码 1 时，表示 funnel 之后的分类形式，修复方法相同
tailscale_needs_operator	运行 sudo tailscale set --operator=$USER，然后重新运行
tailscale_unknown（退出码 1）— tailscale serve --bg 在 60 秒内未完成	CLI 正在等待操作者操作（预检查无法检测到的启用步骤）。让他们手动运行打印出的 tailscale serve --bg <port>，查看提示，然后重新运行
tailscale_needs_login	Linux：运行 sudo tailscale set --operator=$USER，然后运行 sudo tailscale up；macOS：运行 tailscale up，或打开 Tailscale 应用并登录；然后重新运行
tailscale_login_manual（退出码 2）— “tailscale at is not a system install, so gbrain will not run it with sudo”	PATH 中的 tailscale 可由用户写入（例如 ~/.local/bin）；gbrain 绝不会以 root 身份运行它。打印出的命令会指明该路径 — sudo <path> set --operator=$USER && sudo <path> up（单独使用 sudo tailscale 将无法在 sudo 的 secure_path 之外找到二进制文件）。运行该命令表示操作者选择信任该二进制文件：说明这一点，让他们自行运行，然后重新运行打印出的命令
tailscale_receipt_present（退出码 1，plan 失败）— “This brain is already published on your tailnet at ”	存在有效的 Serve/Funnel 映射记录时传入了 --no-tailscale。先运行 gbrain mcp expose --remove --yes，或移除 --no-tailscale
tailscale_daemon_not_running（退出码 2）	macOS 运行 open -a Tailscale；Linux 运行 sudo systemctl enable --now tailscaled；然后重新运行
foreign_serve_config — “tailscale serve already proxies :443 to …”（退出码 1）	向用户展示现有处理程序代理的内容（tailscale serve status）；只有在用户明确同意后才使用 --force。由另一个终端中的前台 tailscale serve 会话持有的处理程序无法接管，必须在该终端中将其停止
foreign_listener — “Something already answers on 127.0.0.1: and no expose receipt claims it”（退出码 1，在发布任何内容之前拒绝；任何监听器都算数 — 非 HTTP 服务接受 TCP 连接也算，即使返回的是 404）	停止另一个进程，换用其他 --port，或传入 --no-service，按原样发布。如果它是因运行中断而遗留的 gbrain 服务，先运行 gbrain mcp expose --remove --yes（无回执恢复）
no_brain_config（退出码 1，plan 失败）— “No brain is configured on this host (gbrain init first), so a service would only crash-loop”	先在此主机上运行 gbrain init，然后重新运行；或者传入 --no-service，仅发布由操作者自行启动的服务。切勿在缺少 brain 时安装服务
pglite_lock 警告 — “a live process holds this PGLite brain (pid N, …)”	告知用户哪个进程持有锁；在该进程退出之前，服务无法启动。停止该进程（或转到 postgres-adopt 以实现并发使用），然后运行 gbrain mcp expose --status
“could not read tailscale serve status” — tailscale.publish 失败（发布：退出码 1，tailscale_<kind>，未发布任何内容；--status：退出码 1；--remove：退出码 1，tailscale_serve_status_unreadable — 有回执时保留回执和包装器；没有回执时仍会移除服务，但保留包装器，作为重新运行时所需的佐证）	命令会以失败关闭，而不会猜测。运行 tailscale serve status --json，应用对应分类的修复方法（操作者／守护进程／登录），然后重新运行相同命令
handler_not_removed（--remove，退出码 1）— “the tailscale handler for port is still present”／“could not be confirmed gone”	off 已运行，但 gbrain 的处理程序仍然存在（或重新读取失败）。服务已移除；回执和包装器是有意保留的。运行 tailscale serve status，修复其报告的问题，然后再次运行 gbrain mcp expose --remove --yes — 切勿运行 serve reset
verify.tailnet: warn — “this host cannot resolve ”（退出码 0）	brain 主机本身已关闭 MagicDNS；运行 tailscale set --accept-dns=true，然后运行 gbrain mcp expose --status。其他设备可能已能访问该服务；不要将此情况视为等待证书
service: manual（没有监管程序：云沙盒、容器）	转发打印出的前台命令和 nohup … & 命令；这是有文档说明的结果，并非失败
verify.local: warn（退出码 2，local_health_timeout）	处理程序已发布、服务已安装且回执已写入 — 此退出码 2 不表示“未发布任何内容”；--status／--remove 都能找到它们。/health 在等待期间未响应：检查 ~/.gbrain/serve/serve.err，然后运行 gbrain mcp expose --status
verify.tailnet: pending（退出码 2，tailnet_health_pending；--status 会报告此状态并以退出码 1 退出）	同样，处理程序、服务和回执都已就位。首次签发证书可能需要一分钟；稍后运行 gbrain mcp expose --status
confirmation_required（退出码 2）	在没有 --yes 的非 TTY 运行中触发。没有任何更改；展示打印出的计划，转达载荷的 user_message，并且只有在操作者同意后才运行其 fix.command（该命令会添加 --yes）
tailscale_no_dns_name（退出码 1）— 节点没有 MagicDNS 名称	在 https://login.tailscale.com/admin/dns 启用 MagicDNS + HTTPS Certificates，然后重新运行；未发布任何内容
tailscale_missing（退出码 1，--no-install）／tailscale_unsupported_platform／tailscale_install_failed（退出码 1）	Tailscale 尚未安装，且未安装（或无法安装）。转发打印出的安装命令或 https://tailscale.com/download，让用户登录，然后重新运行
tailscale_publish_unconfirmed（退出码 1）— serve --bg 以 0 退出，但重新读取时未显示处理程序（或无法读取）	运行 tailscale serve status；gbrain mcp expose --remove --yes 可以清除没有回执的端口处理程序（若 gbrain 尚无包装器或服务，则使用 --force），然后重新运行
service_install_failed（退出码 1）	处理程序已发布，且回执已写入，状态为 service.state: stopped。查看错误和 ~/.gbrain/serve/serve.err，修复后重新运行；或运行 gbrain mcp expose --remove --yes
status_unhealthy（--status，退出码 1）	某项检查失败（tailscale.publish、service、verify.local）；应用对应行的修复方法，然后运行 gbrain mcp expose --yes 进行修复
recovered_without_receipt（--remove，退出码 0）	无回执恢复已完成：报告移除了什么、留下了什么（管理员令牌仍会保留）
切勿通过手动编辑 Tailscale 状态来绕过已分类的错误；
应用打印出的修复，然后重新运行。

阶段 3 — 选择客户端流程和所有者权限

使用成功的公开暴露回执中的 mcp_url 和 admin_token_file；将它们替换示例 URL／默认路径，包括在自定义 GBRAIN_HOME 时。所有者命令应在主机上运行，或在经过单独授权的管理环境中使用该服务受保护的凭据运行。普通连接客户端应将这些步骤交由该管理员处理；其 OAuth 作用域无法授予所有者权限。所有者操作和恢复请遵循 mcp-access 和 MCP 管理。

打开仪表板：

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

通过私密渠道发送一次性链接，不要获取该链接。普通管理 URL 不会进行身份验证。对于待处理的原生授权，请添加 --oauth-request ID，并使用客户端浏览器请求中的确切不透明 ID；随后由所有者单独审核授权。如果请求已过期或服务已重启，则必须在原生客户端中重新启动授权。

预期连接	注册	交付
原生公开 PKCE	mcp admin register，方法为 none，使用确切的客户端回调 URI	原生 OAuth 元数据；无需客户端密钥
原生机密 PKCE	mcp admin register，使用实际的 client_secret_post 或 client_secret_basic 方法，以及确切的回调 URI	通过 --credentials-out 生成的私密 OAuthClientSetup
机器凭据／托管的 bearer 配置	mcp grant --harness ID	供 gbrain connect 使用的私密机器交接信息

对于原生 OAuth，请从预期使用的环境中获取实际重定向 URI 和身份验证方法。必须将下方的 CLIENT_REDIRECT_URI 替换为该确切 URI；它不是建议使用的回调 URI：

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

检查预览，然后不带 --dry-run 再运行一次。对于机密 PKCE，请使用客户端实际的 POST／Basic 方法，并在创建前添加 --credentials-out PRIVATE_FILE。原生注册会创建授权码和刷新授权，而不是机器令牌。使用返回的 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

已知时请使用实际受支持的适配器 ID；generic 会提供手动原生设置说明。原生客户端会发起 OAuth，并自行管理其验证器。OAuthClientSetup 不是供 gbrain connect 或 gbrain mcp verify 使用的机器交接信息。除非所有者明确选择启用 DCR，否则请保持 DCR 关闭；手动所有者注册无需使用 --enable-dcr。

对于使用私密机器交接信息的客户端，请通过同一运行中服务的管理 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 应为真实的适配器 ID（gbrain mcp adapters）：grok-bot、 muse、claude-desktop、codex、claude-code、opencode，等等。
• 检查预览，然后不带 --dry-run 再运行一次以创建客户端。
• 配置文件（memory-reader、memory-writer、coding-agent、operator、 delegating-agent、full）和委派限制定义于 托管环境访问； 默认使用 memory-writer，如果只需要读取，则使用 memory-reader。
• 回执中的信息已脱敏；凭据文件权限为 0600。通过私密渠道将其发送给 客户端，切勿通过聊天发送。

阶段 4 — 在客户端内配置所选连接

客户端	安装
任何原生 OAuth 客户端，包括受支持的桌面应用／云连接器	在其支持的设置中输入原生注册的实际端点、客户端 ID、回调和方法；机密客户端还需提供 OAuth 私钥。请在该客户端中启动授权并获取所有者同意。如果无法手动配置客户端，请遵循其 docs/mcp/ 指南；不要改用机器凭据。
使用私有机器路径的 Grok Bot	在 Bot 内运行：gbrain connect https://your-machine.your-tailnet.ts.net/mcp --harness grok-bot --credentials-file /private/agent-example.json --install --root /workspace/gbrain；将生成的指令启用为原生技能（这是一个可见的独立步骤）
使用私有机器路径的 Muse	同样运行 gbrain connect … --harness muse … --install --root <verified durable root>；首先确定持久的用户文件位置——绝不能使用 /tmp，也不能编造路径
在另一台机器上使用受管理的私有配置的 Claude Code / Codex / opencode	gbrain connect https://your-machine.your-tailnet.ts.net/mcp --harness codex --credentials-file /private/agent-example.json --install；选择实际的适配器
脑主机上的本地 Agent	Postgres：gbrain bootstrap harness --yes --port 3131。PGLite：在服务运行期间，bootstrap harness 必须传入 --token，否则会拒绝执行——请在服务运行前生成令牌（在运行 gbrain mcp expose 前，或短暂停止服务时运行 gbrain auth create local-agents --scopes read,write），然后传入 gbrain bootstrap harness --yes --port 3131 --token <value>；或者跳过钩子，使用受限范围的 gbrain mcp grant … --url http://127.0.0.1:3131/mcp --admin-token-file ~/.gbrain/serve/admin-token --credentials-out /private/<name>.json + gbrain connect http://127.0.0.1:3131/mcp --harness <id> --credentials-file /private/<name>.json --install 路径（仅配置 MCP）
ChatGPT / Perplexity / 其他云 OAuth 客户端	当运行环境位于 tailnet 之外时，必须明确指定 --funnel；请遵循原生 OAuth 路径以及 docs/mcp/ 下对应客户端的页面，使用已发布的 URL

仅限 tailnet 的端点只能由已登录同一 tailnet 的设备访问——如果设备无法解析 your-machine.your-tailnet.ts.net，请在该设备上安装 Tailscale 并登录；不要改用 --funnel。

阶段 5 — 验证

对于私有机器路径，请在客户端的环境中执行：

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" 可证明获准的服务检查已通过；可写授权还会进行随机写入／回读和清理。原生激活仍需单独验证；退出码 2（partial）表示原生验证尚未完成。

对于原生 OAuth，请通过该测试框架的已认证 MCP 连接观察 gbrain://capabilities 和一次获准调用。不要将 OAuth 设置导出内容传递给私有交接验证器。对于任一路径，都要在预期的测试框架中观察调用，并在测试记忆前检查公布的架构。获得授权的可写授权后，只使用无害的合成事实，附带来源信息，并在其来源授权范围内明确设置 visibility: "world"；保留返回的 ID，在新对话中验证能否检索，纠正后将其撤回。无法通过这些远程操作检索或撤回私有事实；切勿为了通过测试而更改真实的私有内容。对于只读访问，请观察一次已认证读取，不要增加写入权限。分别报告注册、设置交付、服务检查、原生调用和清理情况。

随时可进行主机端检查：gbrain mcp expose --status（没有回执时，会以 leftovers_without_receipt 报告残留项，退出码为 1，并给出确切的清理命令）。移除暴露配置和主机服务： gbrain mcp expose --remove（停止并移除服务 — 即使回执显示服务已跳过，但单元仍存在时也会移除 — 使用 --https=443 --set-path=/ off 仅清除 gbrain 的 serve/funnel 处理器，保留已安装并登录的 Tailscale — Linux 操作者偏好也会保留 — 除非使用 --force，否则保留管理令牌；没有回执时 — 发布过程被中断 — 会从磁盘上现有内容恢复：包装器、单元和 --port 对应的 :443 处理器，默认端口为 3131，并保留令牌；只有包装器、单元或服务能够佐证时才会关闭处理器 — 若处理器单独存在，则会报告并保留，直到使用 --force）。若执行 off 后处理器仍存在，绝不会报告为已移除：退出码为 1，错误为 handler_not_removed，并保留回执和包装器以供重新运行。若无法读取 tailscale serve status，两条路径都会以退出码 1 和 tailscale_serve_status_unreadable 终止（服务已移除；回执和／或包装器会保留）— 修复 Tailscale 后，重新运行打印出的命令。拒绝提示时以退出码 2 退出，并显示“未作任何更改。”；使用 --no-service 重新运行时，会保留现有服务。

移除暴露配置不会撤销客户端注册，也不会清除大脑数据。请阅读其影响和版本信息后，使用「MCP 管理」中的所有者生命周期命令，使令牌失效、撤销客户端访问权限，或删除指定客户端。

PGLite 单写入者说明

暴露的服务运行期间，会持有 PGLite 锁。会打开数据库的主机端命令（gbrain doctor、没有所有者文件或受保护的 GBRAIN_ADMIN_BOOTSTRAP_TOKEN 时的 gbrain mcp grant、不带 --token 的 gbrain bootstrap harness）会因 live_serve 立即失败 — 不会等待。请改为通过正在运行的服务进行管理。gbrain sync 和 gbrain sweep --once 是例外：它们会自动委托给正在运行的服务。始终通过 --admin-token-file 进行配置；如果用户需要并发运行本地命令，请转用 postgres-adopt，而不要停止服务。

失败时

对于任何 gbrain 错误 code、退出代码、[AGENT] 块或通知块，请遵循Agent 操作员协议。此技能的具体说明：

• gbrain mcp expose --status 报告 not_exposed（退出代码为 2）或 pending：根据状态提示，等待证书或服务；leftovers_without_receipt（退出代码为 1）表示运行中断，因此请按其 fix 操作。
• 安装 Tailscale 或服务需要先征得用户同意，才能使用 --yes；gbrain mcp expose 在需要确认时仍会以 2 退出（这是有文档记录的旧行为），因此要读取块内容，而不能只看退出代码。
• 客户端收到 invalid_token / insufficient_scope：为该客户端签发范围受限的授权；绝不能为了让它连接而提供管理员凭据。

反模式

• 绝不要优先推荐 ngrok 或云主机；默认使用 Tailscale，只有明确想要其他方案的用户才使用替代方案。
• 这种情况下绝不要运行 gbrain serve --http --bind 0.0.0.0。Tailscale Serve 会终止 TLS，并转发到环回地址；默认绑定方式是正确的。
• 绝不要悄悄传入 --funnel。要说明它会使端点可公开访问，以及该客户端为何需要它。
• 绝不要将管理员令牌或凭据文件粘贴到对话中、提交中，或粘贴到 harness 会记录的命令参数中。
• 绝不要运行 tailscale serve reset、tailscale logout 或卸载 Tailscale 来清理——gbrain mcp expose --remove 只会处理 gbrain 的处理程序。
• 绝不要因为健康检查失败就授予 operator/full/admin 权限。
• 绝不要将 OAuth admin 范围视为所有者权限，也不要将原生 OAuth 设置文件作为私有机器交接文件安装。
• 绝不要因为 mcp verify 通过就声称客户端已连接；必须在客户端中观察到原生激活和新对话中的记忆召回。
• 绝不要从第二个进程打开正在使用的 PGLite 数据库来进行配置。

输出格式

报告主机状态，并为每个客户端分别用一行说明：

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">

按原样引用 gbrain mcp expose --status 和 gbrain mcp verify 的输出（两者均已脱敏）。明确列出每个未经验证的步骤；服务器检查通过绝不能替代在客户端中观察到的记忆召回。