跳转到内容

Agent Toolkit

iMBrace Agent Toolkit 是 iMBrace 官方的 AI 编程代理插件。安装一次,你的代理就知道如何在 iMBrace 上构建:TypeScript/Python SDK、托管的 MCP 服务器、CLI、AI 代理、工作流、知识库和 CRM 数据面板。

插件名为 iMBrace Developer,有两种形式:

  • Claude Code — 六个技能加上托管的 iMBrace MCP 服务器,代理还能读取(如果你允许,也能修改)你的 iMBrace 数据。
  • ChatGPT 和 Codex — 同样的六个技能,以纯技能插件的形式提供。它只包含说明,不调用任何服务,也不保存任何凭据。如需工具,请自行连接 MCP 服务器(其他 MCP 客户端)。

源码和问题反馈:github.com/imbrace-co/imbrace-agent-toolkit(MIT)。

工具包内容

技能用途
imbrace-get-started首次使用:选择环境、安全地获取 API key、完成一次经过验证的调用
imbrace-sdkTypeScript @imbrace/sdk 和 Python imbrace:客户端设置、命名空间、错误处理
imbrace-mcp在任意客户端连接托管 MCP 服务器;OAuth 登录,API key 作为备选
imbrace-cli安装、登录并用脚本驱动 imbrace CLI;在本地运行 imbrace mcp
imbrace-build-agents-workflows端到端构建 AI 代理 + 流式聊天、工作流、知识库、CRM 数据面板
imbrace-vibe-code在 iMBrace 上构建、部署并托管完整应用(遵循 /skill.md)

当你的请求与技能匹配时,技能会自动加载。开启一个新会话,例如问:“Help me get started with iMBrace”。

在 Claude Code 中安装

需要 Claude Code 2.1.275 或更高版本。在终端中:

Terminal window
claude plugin marketplace add imbrace-co/imbrace-agent-toolkit
claude plugin install imbrace-developer@imbrace-developer-tools

或在 Claude Code 会话中:

/plugin marketplace add imbrace-co/imbrace-agent-toolkit
/plugin install imbrace-developer@imbrace-developer-tools

更新:claude plugin marketplace update imbrace-developer-tools;卸载:claude plugin uninstall imbrace-developer。

选择环境

插件把 MCP 服务器添加为 imbrace,插件中不保存任何凭据。它连接到生产环境;各环境的 MCP URL 如下:

环境MCP URL
生产环境(插件的服务器)https://app-gatewayv2.imbrace.co/mcp
Sandboxhttps://app-gateway.sandbox.imbrace.co/mcp
本地部署https://<你的网关>/mcp

要使用其他环境,请自行添加服务器(见下文)。每个环境都有各自的账号、组织和 API key:请在要连接的环境中登录或生成 key。在 URL 上加 ?services= 或 ?tags= 可以缩小列出和可调用的工具范围(参见 MCP 服务器);这只是过滤,不是访问控制。

同时使用多个环境

插件的 imbrace 服务器始终指向生产环境。其他每个环境用各自的名称另外添加,每个服务器分别登录(如果只想使用其他环境,可在 /mcp 中停用插件的服务器):

Terminal window
claude mcp add --transport http imbrace-sandbox https://app-gateway.sandbox.imbrace.co/mcp
claude mcp add --transport http imbrace-onprem https://<your gateway>/mcp

然后 /mcp → 选择每个服务器 → Authenticate。对于未启用 OAuth 的网关,改为在命令中加上 --header "Authorization: Bearer $IMBRACE_SANDBOX_API_KEY",每个环境使用一个 key 变量。工具按服务器分别列出(例如 mcp__imbrace-sandbox__listBoards),提问时请说明你指的是哪个环境。

ChatGPT 和 Codex

同样的技能将以 iMBrace Developer 的名称发布到 OpenAI 插件目录;发布时会在工具包 README 中加上目录链接。这个包只包含技能:如果也想让 Codex 使用 iMBrace 工具,请按其他 MCP 客户端中的说明把 MCP 服务器添加到 Codex。

连接 MCP 服务器

有两种登录方式,每个连接选一种:OAuth(在浏览器中登录,无需复制任何东西)和 API key(api_...)。

使用 OAuth 登录

在已启用 OAuth 的网关上:

  1. 在 Claude Code 中运行 /mcp,选择 imbrace,然后选择 Authenticate。
  2. 在打开的浏览器中登录 iMBrace。
  3. 在授权同意页面选择此连接使用的组织。
  4. 选择要授予的权限:只读,或读 + 写(如有需要,还可以加上删除)。写和删除可以取消勾选。
  5. 回到 Claude Code,工具就会出现。试试 “List my iMBrace boards” — 它应该会调用 listBoards 之类的工具。

授予的权限

Scope允许
imbrace.read读取类工具。始终授予。
imbrace.write创建和更新类工具
imbrace.delete删除类工具(包含写权限)
  • 组织由授权决定。 每次调用都在你于同意页面选择的组织中运行;客户端或模型发送的组织会被覆盖。要在其他组织中工作,请重新登录。
  • 写和删除权限只来自这些 scope。使用 OAuth 时,URL 上的 ?allowWrite 和 ?allowDestructive 会被忽略。
  • 每次工具调用都会以你的身份通过常规 API 重放,因此你在该组织中的成员身份、角色权限和许可证依然生效。

会话、切换与撤销

  • 客户端会自行保存并刷新 token。访问 token 有效期为 1 小时,并通过刷新 token 续期,所以不需要每小时登录一次。
  • 切换组织或权限: /mcp → imbrace → 清除认证(clear authentication),然后再次 Authenticate 并重新选择。
  • 撤销: 在客户端中清除认证即可删除其保存的 token。访问 token 不会对照撤销列表检查,所以已签发的 token 在过期前(最多 1 小时)仍然有效。把某人移出组织或修改其角色会立即生效,因为网关在每次调用时都会检查成员身份和角色。

改用 API key

在网关尚未启用 OAuth、用于 CI 和无界面机器、或客户端不支持 OAuth 时,使用 API key。在 iMBrace Portal 的 GovernCore → Generate External Token 生成组织 key(api_...)(参见获取 API Key),并自行把它放进环境变量 — 永远不要把 key 粘贴到聊天中或提交到代码库。

在 Claude Code 中用 key 添加服务器;如果不想出现两个条目,请停用插件的 imbrace 服务器(或整个插件):

Terminal window
claude mcp add --transport http imbrace https://app-gatewayv2.imbrace.co/mcp \
--header "Authorization: Bearer $IMBRACE_API_KEY"

API key 连接默认只读,除非 URL 带有 ?allowWrite=1(创建和更新)或 ?allowDestructive=1(还包括删除)。固定的 Authorization 头会关闭客户端的 OAuth 流程,所以每个连接只用一种方式。

其他 MCP 客户端

示例使用生产环境;请把主机名替换为你所在环境的网关。OAuth 方式只适用于已启用 OAuth 的网关。

OAuth:

Terminal window
claude mcp add --transport http imbrace https://app-gatewayv2.imbrace.co/mcp

然后 /mcp → imbrace → Authenticate。使用 API key 时,请用改用 API key中的命令。

Web、桌面和移动端的 Claude(自定义连接器)

不使用 Claude Code 时,可以把 iMBrace 作为自定义连接器(custom connector)连接到 Claude——包括 claude.ai、Claude Desktop 和移动应用。这需要网关已启用 OAuth:自定义连接器无法发送 API key。

  1. 打开 Settings → Connectors,选择 Add custom connector。如果是 Team 或 Enterprise 套餐,需要由 Owner 先在组织的连接器设置中添加,成员再在自己的设置中连接。
  2. 按环境命名,例如 iMBrace 或 iMBrace (sandbox),并粘贴选择环境中的 MCP URL。高级设置中的 OAuth client ID 和 secret 留空:Claude 会自行向 iMBrace 注册。
  3. 选择 Connect,登录 iMBrace,并在授权(consent)页面选择组织和访问权限(读取、写入、删除)。
  4. 在对话中通过工具菜单启用该连接器,然后提问,例如 “List my iMBrace boards”。
  • 每个环境和组织各用一个连接器。 要切换组织或权限,请断开连接器后重新连接。
  • 网关必须能从互联网访问。 Claude 从 Anthropic 的云端连接,而不是从你的电脑连接。位于 VPN 或防火墙后的本地部署网关只能通过 Claude Code,或在能访问该网关的机器上运行的其他客户端使用。
  • 在 claude.ai 上添加的连接器也可以在 Claude Desktop 和移动应用中使用。

故障排查

现象原因解决方法
/mcp 显示 imbrace 失败:Dynamic Client Registration rejected (HTTP 404) … Cannot POST /register该网关未启用 OAuth,无法开始登录停用插件的 imbrace 服务器,改用 API key 连接
401 并带有 invalid_token未登录,或登录已过期/mcp → imbrace → 清除认证,然后再次 Authenticate
使用 API key 时出现 401key 错误、已过期、属于其他环境或为空检查 key 和网关主机名
403你在该组织中的角色缺少相应权限联系组织管理员
402 plan_feature_unavailable(MCP access is not included in your plan)该组织的套餐不包含 MCP 访问权限请 iMBrace 管理员为该套餐开启 MCP 访问,或重新 Authenticate 并选择套餐包含 MCP 的组织
缺少写入或删除类工具,或提示 tool not enabledOAuth:授权中没有 imbrace.write / imbrace.delete。API key:URL 中没有 ?allowWrite=1 / ?allowDestructive=1。或者 ?services= / ?tags= 过滤排除了该工具重新认证并授予写(或删除)权限,或修正 URL
自定义连接器无法连接网关未启用 OAuth,或无法从互联网访问检查 <gateway>/.well-known/oauth-protected-resource/mcp。改用已启用 OAuth 的网关,或在 Claude Code 中使用 API key

支持

在工具包的 GitHub Issues 中报告问题和提问。

MCP 服务器由 iMBrace Limited 运营。调用以你登录的 iMBrace 用户和组织(或你的 API key)身份运行,受 iMBrace 隐私政策和条款约束。技能只会建议命令和代码;你运行它们时,会调用 iMBrace 的服务(以及用于安装 SDK 和 CLI 的 npm 或 PyPI),完整列表见插件 README 的 Network and data 部分。