ChatGPT Connector

通过 MCP 与 OAuth 把网页里的 ChatGPT 接到本地工作站。

ChatGPT 不能直接访问 127.0.0.1。herdr-mcp 因此把本机开发环境放在一个稳定的远程 MCP 入口后面：ChatGPT 连接 Cloudflare Edge，工作站再通过出站 WSS 主动连到 Edge。

ChatGPT
  │ OAuth + MCP
  ▼
Cloudflare Edge
  │ authenticated WSS
  ▼
herdr-link / herdr-mcp
  │
  ├─ files / Git / shell
  └─ Herdr workspaces / panes / agents

如果本地 runtime 和 Edge 还没有部署，先看安装。本页集中解释 ChatGPT 这一侧：怎样连接、为什么需要 OAuth、什么叫“连接成功”、工具快照为什么会陈旧，以及出现问题时应该查哪一层。

ChatGPT 的 Developer mode、Apps / custom MCP UI 和套餐权限仍在持续演进。项目文档描述 herdr-mcp 需要满足的协议边界；具体菜单名称和账户可用范围以 OpenAI 当前官方文档为准。

连接前先理解三个不同的“成功”#

1. OAuth 成功#

ChatGPT 知道这个 MCP 服务是谁，也拿到了访问授权。

2. MCP 握手成功#

ChatGPT 能完成 initialize / discovery / tools/list。

3. 工作站真的可达#

工具调用能穿过 Edge 和 workstation link，最终看到本机 Herdr / Git / shell。

这三层可以独立失败。所以“设置页面显示已连接”并不等于“当前聊天已经能改代码”。

最可靠的验收是在新会话里执行一次真实 herdr_inspect，直接确认工作站数据可达。

创建 Connector / Custom MCP App#

当前 ChatGPT Web 的开发者模式可以添加自定义 MCP 应用。界面和套餐权限可能变化，整体流程保持一致：

打开 ChatGPT 设置 → 账户安全与登录，启用 开发者模式（Developer mode）；
进入“插件 → 浏览插件”，点击右上角 +，选择 Create APP，创建 MCP 应用。建议名称使用 herdr，也可以自定义 App 名称；
MCP URL 填完整地址，必须包含 /mcp：
```
https://<your-edge-origin>/mcp
```
完成浏览器 OAuth。首次授权页会根据浏览器语言自动使用中文、英文或日文。第一步复制 herdr-mcp connector approve <approval-request-id> 到终端；该命令先检查本机 herdr-mcp 服务和 Herdr server 是否就绪，第二步才要求输入页面上的 6 位验证码。已批准的 WebChat Connector 仍只有普通 MCP 权限，不能继续批准另一个 Connector；
创建或打开 ChatGPT Project。首次需要读取工作站数据或执行 Herdr 动作时，选择或 mention 你为这个 Connector 设置的 App 名称；默认/示例名称是 herdr，但自定义名称也支持。扩展会从 ChatGPT 真实 App pill 的 provider-owned data-keyword 读取身份，并写入当前 conversation/Project 的既有 binding。后续 Herdr 自动继续、Agent 结果、恢复、handoff 和 Browser Actuation 都复用这个已观察到的真实身份，因此同一会话不需要每轮重复 mention。如果之后 Edge、Link、runtime 都健康但工具仍消失，应按 attachment 回归处理；再次选择该 App 只是恢复 workaround，不是正常使用流程。

不要填写本机 HERDR_MCP_TOKEN。 ChatGPT 公网入口使用 OAuth；静态 bearer 只用于本机 curl / Cursor 和兼容路径。

如果组织对自定义 MCP 应用有管理员审批、Action control 或 RBAC，先满足 Workspace 侧策略。herdr-mcp 无法绕过 ChatGPT 自己的组织治理。

为什么 OAuth issuer 不能随便换#

一个 Connector 不只是记住 /mcp 地址。OAuth metadata、issuer、resource audience 和 MCP origin 必须互相一致。

推荐配置：

HERDR_MCP_BASE_URL=https://herdr-edge.example.workers.dev
MCP URL=https://herdr-edge.example.workers.dev/mcp

HERDR_MCP_BASE_URL 不带 /mcp。

Edge origin 应当稳定。本地 runtime 可以升级、A/B 切代甚至回滚；只要 contract 和 Edge identity 不变，ChatGPT Connector 不需要跟着重新配置。

这也是项目把 Edge 生命周期和本机 runtime 生命周期分开的原因。

OAuth 链路#

ChatGPT 会探索远程服务器的 OAuth / protected-resource metadata。Dynamic Client Registration（DCR）只负责登记 client metadata，不等于授权。从 v0.4.6 开始，新 Connector 必须由已登记 Device/operator 控制通道明确批准后才能取得可用 token：

Connector
  │ metadata discovery + DCR
  │ authorize + PKCE
  ▼
Herdr pending approval 页面
  │ request id + 短期 6 位批准码
  └─ 任意已登记电脑：
       herdr-mcp connector approve <request-id>
  ▼
authorization code → token → /mcp

同一个 Worker 内的已登记设备在这条控制面上没有 owner/member 高下之分；Device/operator 负责 fleet 管理。已批准 Connector 只获得普通 MCP 访问，不能批准/撤销其它 Connector，也不能创建 pairing 或 revoke Device。v0.4.6 之前、在没有明确批准步骤时签发的 OAuth token 可以继续做普通 MCP 兼容访问，直到 operator 显式撤销其 client grant。当前 Connector 实例用 herdr-mcp connector list 查看不可变 connector_id；清单会保留稳定的 Connector 名称、授权时间和节流后的最后一次真实 MCP 使用时间。用 herdr-mcp connector revoke <connector-id> --confirm 可以精确撤销单个实例；更早、还没有 Connector-instance 记录的 legacy client 仍可通过兼容 grant tombstone 被彻底封禁。

批准码是单用途、短时、限制错误次数的交互凭据，不接受普通 CLI argv 传入。2026-09-08 的真实 ChatGPT UAT 已确认：在 ChatGPT 中删除/Disconnect 自定义 Connector，目前不会可靠地向 Herdr 发送 RFC 7009 revoke 请求。因此不能把 provider UI 的 Disconnect 当成 Worker 端 revoke 事件。operator 随时可以手动精确 revoke 某个 conn_*；Worker 还会自动回收连续 30 天没有 Connector 活动的 active 实例。自动清理只删除该实例自己的 access/refresh credential，并保留非敏感审计记录，包括 Connector 名称、授权时间、最后使用时间、撤销时间，以及 inactive_30d 原因。真实 MCP 使用最多每 24 小时更新一次 last_used_at，避免不必要的 Durable Object 写入。

实现兼容 Client ID Metadata Document、PKCE、JWT access token 和当前 ChatGPT MCP 客户端行为。

排查时重点关注：

public origin 是否一致；
OAUTH_ISSUER 是否与用户实际访问的 origin 一致；
redirect/token 请求是否成功；
token 的 audience 是否对应 MCP resource；
Edge 是否能继续把工具调用路由到在线 workstation。

OAuth 成功以后 workstation 仍可能离线，所以不要把 OAuth 当作完整健康检查。

为什么新会话很重要：tool snapshot#

ChatGPT 使用经过审核的 MCP action 冻结快照。只升级本地 runtime 或部署 Edge，并不会自动把新增 action 启用到已经批准的 Workspace App 中。

Herdr 从 0.4.3 起明确区分两层 contract：

ChatGPT public contract（first-party DEV/PROD）：epoch 8 / 19 actions；workstation runtime execution contract：epoch 5 / 18 tools。 第 19 个 action 是 Edge-local herdr_devices，不会转发到 workstation。紧邻上一代冻结的 epoch 4 与冻结的 epoch 2 catalog 仅作为有界的 rollback/compatibility 基线保留，epoch 3 仅属历史，公共 Edge epoch 3 身份仍作为非 DEV/PROD 的有界基线保留。

典型现象：

服务器已经 public epoch 8 / 19 actions
        │
        ├─ 已刷新 action 集：可以看到 19 actions ✓
        │
        └─ 旧/冻结 action 集：可能仍是更旧的 action 集

升级 runtime 后：

确认 Edge / runtime 暴露的是当前版本。当前 Release 会通过 herdr-mcp update check|status 暴露 Worker drift；交互式 herdr-mcp update 会在 Runtime 激活后 reconcile 安全的同-contract 已有 Worker，herdr-mcp worker update 是直接修复入口；
不要仅因为 Runtime 或已有 Worker 做了原地升级就断开、删除或重新添加 Connector；Worker reconcile 会保留 public OAuth origin 与 Connector credentials；
Herdr public action catalog 发生变化时，通过当前账户可用的 Workspace App 管理入口刷新、审核并发布 actions；新增 action 如需显式启用则同时启用；
action snapshot 更新后，用新会话重新验证。更新 Worker 代码是获得新版 Edge 工具描述的必要条件，但已经审核过的 ChatGPT action snapshot 仍可能保持冻结，直到 App actions 被刷新。

Epoch 8 验收：查询当前 Connector 指向的 Worker /info，确认 publicContract.epoch=8；刷新 ChatGPT 的 Herdr actions 后，在新会话核对仍有 19 个工具（11 read、8 write），且 herdr_call 说明包含 Browser actions require an explicit device、herdr_exec 说明包含 shell scripts, pipes, or redirects。再执行只读文件/Git 查询和简短命令。浏览器扩展 Reload 不会刷新 MCP 工具快照。

不要为了陈旧 tool snapshot 重装 workstation。v0.4.2 runtime 仍可继续执行 epoch-2 / 18-tool workstation contract；只有升级到 v0.4.3 后才获得新的多设备 runtime 能力。

工具 catalog 真正发生不兼容变化时，项目使用 contract epoch 管理；普通 runtime bugfix 不应该随意改变 catalog。

为什么工具少反而更适合 ChatGPT#

Herdr 原生 Socket API 有大量方法。把每个方法都变成 MCP tool，会让 ChatGPT 每轮携带大量 schema，也让工具选择变得困难。

ChatGPT 常用的是：

herdr_inspect
herdr_since
herdr_fs_*
herdr_git
herdr_exec*
herdr_prompt

低频 Herdr 原生能力再由 herdr_methods → herdr_call 动态发现。

所以 tools/list 很短，但能力并没有被裁掉。

一次真实会话应该怎样开始#

推荐的第一条任务可以很简单：

检查当前 Herdr 工作区和 Git 状态。只读，不要修改。

理想流程：

ChatGPT 调 herdr_inspect；
读取一次 herdr_skill 获取当前操作策略；
选定目标 managed Git root；
用 herdr_git status / herdr_fs_read 获取事实；
回答用户。

之后真正开发时再进入 patch / exec / agent delegation。

这比用“工具数量显示正确”作为唯一验收更可靠。

权限确认卡是谁控制的#

ChatGPT 对写入或有风险的 App action 可能显示确认 UI。这个行为属于 ChatGPT 产品安全层，herdr-mcp 服务端无法保证“永远不询问”。

项目浏览器扩展可以在满足严格条件时自动处理页面 DOM 内明确的 Allow/允许卡片，但它不会绕过 Workspace 权限，也不会处理浏览器/系统原生权限对话框。

当前 ChatGPT Project 自动化只有在：

Options 允许 Project 自动化；
当前 Project HUD 为 自动开；
页面出现可识别、可见、可用的允许动作；

时才进行自动点击。自动关 时只观察。

详见浏览器连续工作与自动继续、恢复和接力。

Streamable HTTP 与 ChatGPT 兼容层#

下面属于维护者参考，普通用户不需要为了连接成功理解全部细节。

ChatGPT 路径保持无状态#

herdr-mcp 对 ChatGPT 的 MCP HTTP 路径不依赖长期 Mcp-Session-Id。实践中，runtime 重启后客户端继续复用 stale session id 会产生 Session terminated 一类假故障。

长命令状态由 herdr_exec_start/read/kill 独立管理，不需要绑定 MCP HTTP session 生命周期。

initialize / tools/list#

ChatGPT MCP 客户端对协议版本和响应形态有明确兼容需求。项目的兼容层负责：

discovery / initialize；
protocol-version negotiation；
SSE / JSON 响应形态；
CallToolResult 的结构化内容和 image 透传；
OAuth 错误与 JSON-RPC 错误语义分离。

不要为了修一个客户端兼容问题把公共 tool schema 随意改掉。

schema 是一个整体#

一个不兼容的 inputSchema 可能导致 ChatGPT 拒绝整份 tool catalog。历史上需要特别谨慎的 JSON Schema 结构包括自由对象、某些 additionalProperties 形态以及客户端不接受的约束关键字。

因此改工具输入时必须跑真实 ChatGPT UAT，不能只验证本地 MCP inspector。

长任务为什么还需要浏览器扩展#

MCP 是请求驱动的。ChatGPT 把任务成功交给一个 Herdr Agent 后，工具调用可能已经返回，而 Agent 仍在本机工作。

ChatGPT: “已提交任务”
        ↓
本轮网页回合结束

Herdr Agent: working ... working ... done

没有额外通道，Agent done 并不会自动让 ChatGPT 开始下一轮。

浏览器扩展负责把本地 progress / settled 事件送回绑定会话，并处理回复卡住和长对话 handoff。因此：

Connector 解决 ChatGPT → workstation；
浏览器 continuity 解决 workstation → ChatGPT。

两条方向合起来才适合持续数小时的网页开发工作。

从症状定位故障层#

症状	优先检查
Connector 根本添加不了	public URL / OAuth metadata / Workspace developer permissions
OAuth 成功，聊天里没有工具	tools/list / schema / App action refresh / 旧会话 snapshot
能看到工具，但 `herdr_inspect` 报 workstation offline	herdr-link / workstation identity / runtime health
`herdr_inspect` 正常，文件工具失败	managed Git root / readonly / path gate
shell/Agent 工作了但网页不继续	browser extension binding / Auto / progress channel
显示 Session terminated	MCP compatibility / stale session semantics，不要先怀疑 Git 仓库

完整排查顺序见故障排查。

最低验收标准#

一次真正成功的 ChatGPT 接入至少满足：

OAuth 完成；
新会话能看到当前 contract；
herdr_inspect 返回真实 workstation；
能读一个 managed Git 项目；
能执行一条安全测试命令；
写操作的确认和权限行为符合预期；
长任务场景下，安装扩展后能收到 progress / settled 回推。

当这些都成立时，ChatGPT 才真正从“远程聊天窗口”变成连接到本机 Herdr 的开发 planner。