BRYDGE

brydge-mcp

检查 Agent 的工作是否确实完成。

这是作为 MCP 服务运行的 BRYDGE。Agent 执行操作前，BRYDGE 会判断是否允许执行。之后，BRYDGE 会使用自己的凭据读取目标系统（例如支付处理商或工单系统）中的记录，再报告工作是否按许可完成。Agent 自称完成的内容会与这一结论一同保留，但绝不会影响结论。

工具

工具	功能
brydge_supervise	执行前先征求许可。ALLOWED 会返回一个授权 ID，供 Agent 写入该操作所创建的记录中。ESCALATED 表示由人员决定，Agent 不得执行操作；使用相同的 idempotency_key 再次询问时，会返回他们的答复。
brydge_report_outcome	报告 Agent 认为发生的情况。
brydge_verify	读取目标系统当前的记录，并说明工作是否完成。
brydge_get_finding	返回 BRYDGE 目前查明的情况，不会再次读取记录。免费。
brydge_get_headroom	说明 Agent 每 24 小时可执行多少项操作，超过后需要征求人员意见。

服务还会向模型提供指示：先询问，引用授权，报告，然后在声称工作已完成前进行验证。

先设置 BRYDGE

在 BRYDGE 中完成以下设置一次即可：

1. 在 Connect 页面上签发 API 密钥。
2. 声明操作的价值。 BRYDGE 会按该价值收取一定比例的费用，并且不会检查未定价的操作。
3. 为该操作注册目标系统：BRYDGE 从何处读取记录，以及它使用的只读凭据。BRYDGE 为 Stripe 退款预设了配置。
4. 在 BRYDGE 中该 Agent 的页面上，向其签发授权以执行该操作。没有授权时，每次调用都会交由人员处理，只有人员批准后 Agent 才能执行（请参阅由人员决定）。

授权规定 Agent 可以执行哪些操作；可用额度则规定每 24 小时内可以执行多少次。新 Agent 每天可以执行一项操作；BRYDGE 每次检查并确认报告属实后，额度都会提高。

添加到 MCP 客户端

大多数客户端都使用此配置（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "brydge": {
      "command": "npx",
      "args": ["-y", "brydge-mcp"],
      "env": {
        "BRYDGE_API_KEY": "brydge_sk_...",
        "BRYDGE_ACTOR": "agent:refund-ops"
      }
    }
  }
}

在 Windows 上，npx 是一个 .cmd 文件，只有通过 shell 或 MCP SDK 启动命令的客户端才能按名称运行它。如果客户端报告 spawn npx ENOENT，请改为通过命令 shell 启动：

{
  "mcpServers": {
    "brydge": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "brydge-mcp"],
      "env": {
        "BRYDGE_API_KEY": "brydge_sk_...",
        "BRYDGE_ACTOR": "agent:refund-ops"
      }
    }
  }
}

在 Claude Code 中：

claude mcp add brydge -e BRYDGE_API_KEY=brydge_sk_... -e BRYDGE_ACTOR=agent:refund-ops -- npx -y brydge-mcp

设置项
BRYDGE_API_KEY	BRYDGE API 密钥。必填。
BRYDGE_ACTOR	BRYDGE 用来识别此 Agent 的名称，例如 agent:refund-ops。授权会签发给此名称。必填。
BRYDGE_URL	BRYDGE 的运行地址。留空则使用 BRYDGE 托管服务。

Agent 的名称来自此配置，绝不会由模型提供，因此 Agent 无法借用其他 Agent 的权限。每个 Agent 运行一个服务。

Agent 如何使用

1. 先询问。 退款、付款或进行其他更改前，Agent 会调用 brydge_supervise，并提供操作、目标和相关事实，例如 {"amount": 4200}。
2. 引用授权。 如果答复为 ALLOWED，Agent 就会执行操作，并将授权 ID 写入目标系统保存该信息的位置。对于 Stripe 退款，该位置是 metadata.brydge_authorization。BRYDGE 仅通过此 ID 查找工作，不会使用其他信息。
3. 报告。 Agent 使用 brydge_report_outcome 报告其认为发生的情况。
4. 验证。 在声称工作已完成前，Agent 会调用 brydge_verify。

brydge_supervise 接受一个 idempotency_key，用于标识一项计划执行的操作，例如 refund:ch_123。使用相同的键和相同的详情再次询问，仍视为同一请求：重试会得到相同答复；如果先前升级处理的请求已有人员答复，则会返回该答复。将某个键用于不同的操作时，绝不会得到另一项操作的答复，因为服务端还会将所询问的内容一并纳入哈希计算。

人员作出决定时

在 BRYDGE 中，升级处理的操作会等待人员决定。服务端不会等待：模型会被告知暂勿操作，并在人员作出答复后再次询问：

ESCALATED. Do not carry this out: a person decides. No mandate lets agent:refund-ops refund yet, so a person decides. A person has been asked. Ask again with the same idempotency key once they have answered: if they allow it, the answer is ALLOWED. Authorization: cmurkt5mw000i7dev66vu5afm.

当模型再次使用相同的 idempotency_key、操作、目标和事实调用 brydge_supervise 时，BRYDGE 会返回人员的决定：

人员	decision	settled	告知模型的内容
尚未答复	ESCALATED	null	暂勿操作；在人员答复后再次询问。不会重复询问该人员。
已允许	ALLOWED	"ALLOWED"	执行此操作，并引用相同的授权。
已拒绝	ESCALATED	"REFUSED"	REFUSED. A person refused this: do not carry it out.，并附上拒绝理由。

详情不同的请求属于不同的操作，因此允许退还 42 英镑，并不意味着 Agent 可以退还 420 英镑。

每项授权只适用于一项操作。对已执行操作的重试会得到相同的 ALLOWED，并且模型会被告知：如果已执行该操作，就不得再次执行。如果同一授权下的操作执行了两次，检查会报告 MISMATCH，原因是 DUPLICATE_EXECUTION。

检查可以发现什么

state	含义
VERIFIED	记录显示工作已按许可执行。
FAILED	记录显示已尝试执行，但未成功。
MISMATCH	记录显示的内容与许可不符。reason 会说明原因：AMOUNT、TARGET、ACTOR、ACTION、DUPLICATE_EXECUTION、UNAUTHORISED_EXECUTION 或 CORRELATION。
UNKNOWN	BRYDGE 无法判断。NO_MATCH 表示记录中没有这项授权的相关内容；其他原因表示 BRYDGE 无法读取记录。未知不等于失败。
PENDING	目标系统表示工作仍在进行。

调用 brydge_verify 时，它会读取记录。检查发现新内容时会计费；没有任何变化时再次询问则免费。目标系统的报告窗口结束后（除非另行设置，默认为 60 分钟），BRYDGE 也会自行检查每项操作；调用 brydge_get_finding 读取检查结果免费。

协议

服务端通过标准输入／输出（stdio）使用 MCP 通信。它基于官方 TypeScript SDK 构建，在同一进程中为客户端提供 2026-07-28 修订版以及 2025 年的各个修订版。当无法向 BRYDGE 发起请求时（例如密钥错误、操作未声明值、触发速率限制或 BRYDGE 无法访问），工具会返回模型可读取的错误，并且不会执行任何操作。

限制

• BRYDGE 将目标视为一项工作。同一目标的第二条记录若携带不同的授权，例如对同一笔扣款进行第二次部分退款，将报告为 MISMATCH。
• 服务端不会等待人员作出决定。升级处理的操作会以告知模型由人员决定而结束；只有模型使用相同的 idempotency_key 和相同的详情再次询问时，人员的答复才会传达给 Agent。使用新密钥发起的请求会重新进行决定。
• 服务端看不到操作本身，因此无法阻止操作被再次执行。操作是否已经执行由模型负责记住；当 BRYDGE 曾对相同请求作出答复时，服务端会告知模型。

开发

npm install
npm test          # a real MCP client against the server in both protocol eras, and the built command over stdio
npm run test:int  # against a running BRYDGE; see tests/integration
npm run build

许可证

MIT