跳转到内容
tool-bridge

把 tool-bridge 提供给 MCP Client

tool-bridge 可以在 /<base>/~mcp 暴露 Streamable HTTP MCP 入口。它不是另一套工具注册表，而是把当前 Bearer 身份可见、可调用的 HTBP 工具实时投影给 MCP Client。

什么时候使用

Section titled “什么时候使用”

适合已经运行 tool-bridge，希望让支持远端 HTTP MCP 的 Agent 或客户端复用同一棵权限树的场景。客户端不需要知道工具来自 MCP、HTTP、Plugin 还是 Device。

如果你的目标是把一个现有 MCP Server 接入 tool-bridge，请改读接入上游 MCP Server。两个方向使用不同的 URL、凭证与验收方式。

前置条件

Section titled “前置条件”
  • 一个可访问的 HTTPS BaseURL；
  • MCP Client 支持 Streamable HTTP；
  • 一把给该客户端专用的 tool-bridge SK；
  • SK 至少拥有目标路径的 read 与 call，且不包含无关管理权限。

不要把 Admin SK 配进桌面客户端、共享配置或团队模板。先按最小权限 SK确定允许的路径与动作。

配置 MCP 入口

Section titled “配置 MCP 入口”

在客户端中填写 HTTP endpoint 和认证头：

URL: https://tb.example.com/~mcp
Authorization: Bearer <scoped-tool-bridge-sk>

如果网关挂载在子路径，保留对应 base：

https://tb.example.com/<base>/~mcp

不同客户端的字段名和配置文件形状会变化，以当前客户端文档为准；tool-bridge 侧稳定契约是 endpoint 与 Bearer 身份。

客户端会看到什么

Section titled “客户端会看到什么”

tools/list 每次都按当前 Bearer 身份从树中生成结果，不是安装时缓存的固定清单：

  • 只投影当前 SK 可读且可调用的工具；
  • 始终包含用于运行时下钻的 tb_help 与 tb_list_nodes；
  • 仅在宿主启用全局 Search 时包含 tb_search；
  • 工具名会编码为 MCP-safe 形式，必须使用 tools/list 返回的名称。

客户端不应从 HTBP path 自行拼接 MCP 工具名，也不应把一次 tools/list 的结果当作长期静态契约。

Device Mailbox 仍是一条工具调用

Section titled “Device Mailbox 仍是一条工具调用”

入站 ~mcp 不会为离线设备额外生成一个 enqueue tool。设备命令声明 delivery: both 时，投影后的 input schema 会增加可选 ~delivery: realtime|mailbox|fallback；mailbox-only 命令只允许 mailbox|fallback；realtime-only 命令不增加该字段。

MCP Client 在同一次 tools/call 中传入 ~delivery。显式选择后，成功结果保持可判别：

{ "delivery": "realtime", "result": {} }

或：

{ "delivery": "mailbox", "operation": { "operationId": "dop_..." } }

fallback 只在 gateway 能确定实时调用尚未派发时入队；业务错误或“可能已发送但结果未知”不会创建第二次执行。operation 查询/取消、歧义终态与设备恢复后的消费流程见Device 离线投递与 Mailbox。

权限与会话边界

Section titled “权限与会话边界”

/~mcp 是无状态适配器：每个请求都会重新校验 Bearer 身份、权限与当前节点状态，不依赖某个网关进程里保存的 MCP session。

这意味着：

  • 吊销 SK 后，后续请求立即失去对应能力；
  • 新挂载或卸载的工具会反映到后续 tools/list；
  • provider 错误、超时和权限判断与 HTTP、CLI、Dashboard 走同一行为边界；
  • 调用者 SK 不会被转发给上游 provider。

成功证据

Section titled “成功证据”
  1. MCP Client 能连接 ~mcp，并完成一次 tools/list；
  2. 列表只包含测试 SK 被授权的工具；
  3. 选择一个只读工具完成真实调用；
  4. 去掉目标路径的 call 后，工具不再成为可调用入口；
  5. 吊销该客户端 SK 后，后续 MCP 请求失败，但不影响其他身份。

常见失败

Section titled “常见失败”
现象 第一检查点
客户端连接失败 确认使用 HTTPS、完整 ~mcp 路径，并保留反向代理的请求体和认证头
tools/list 为空 当前 SK 没有同时满足目标工具所需的 read 与 call
找不到 tb_search Search 是可选 capability；从根 ~describe 确认宿主是否装配
工具名与 HTBP path 不一致 入站投影会编码名称；以 tools/list 返回值为准
能看到帮助但调用失败 回到工具级 ~help 检查 schema，再区分 403、上游业务错误和 provider 不可用

移除与轮换

Section titled “移除与轮换”

从 MCP Client 删除 endpoint，或吊销/轮换该客户端专用 SK。该操作不会卸载树上的工具节点，也不会影响其他 Agent、CLI 或 Dashboard 身份。

下一步

Section titled “下一步”