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-sdk | TypeScript @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 或更高版本。在终端中:
claude plugin marketplace add imbrace-co/imbrace-agent-toolkitclaude 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 |
| Sandbox | https://app-gateway.sandbox.imbrace.co/mcp |
| 本地部署 | https://<你的网关>/mcp |
要使用其他环境,请自行添加服务器(见下文)。每个环境都有各自的账号、组织和 API key:请在要连接的环境中登录或生成 key。在 URL 上加 ?services= 或 ?tags= 可以缩小列出和可调用的工具范围(参见 MCP 服务器);这只是过滤,不是访问控制。
同时使用多个环境
插件的 imbrace 服务器始终指向生产环境。其他每个环境用各自的名称另外添加,每个服务器分别登录(如果只想使用其他环境,可在 /mcp 中停用插件的服务器):
claude mcp add --transport http imbrace-sandbox https://app-gateway.sandbox.imbrace.co/mcpclaude 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 的网关上:
- 在 Claude Code 中运行
/mcp,选择imbrace,然后选择 Authenticate。 - 在打开的浏览器中登录 iMBrace。
- 在授权同意页面选择此连接使用的组织。
- 选择要授予的权限:只读,或读 + 写(如有需要,还可以加上删除)。写和删除可以取消勾选。
- 回到 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 服务器(或整个插件):
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:
claude mcp add --transport http imbrace https://app-gatewayv2.imbrace.co/mcp然后 /mcp → imbrace → Authenticate。使用 API key 时,请用改用 API key中的命令。
写在 .cursor/mcp.json(或 ~/.cursor/mcp.json,对所有项目生效)。OAuth — Cursor 随后会提示登录该服务器:
{ "mcpServers": { "imbrace": { "url": "https://app-gatewayv2.imbrace.co/mcp" } }}API key:
{ "mcpServers": { "imbrace": { "url": "https://app-gatewayv2.imbrace.co/mcp", "headers": { "Authorization": "Bearer ${env:IMBRACE_API_KEY}" } } }}写在 ~/.codex/config.toml:
[mcp_servers.imbrace]url = "https://app-gatewayv2.imbrace.co/mcp"OAuth:运行 codex mcp login imbrace(适用于支持 MCP OAuth 的 Codex 版本)。API key:改为在 [mcp_servers.imbrace] 下添加 bearer_token_env_var = "IMBRACE_API_KEY"。
OAuth:将 iMBrace 添加为自定义连接器(custom connector),参见 Web、桌面和移动端的 Claude。
使用 API key 时(仅 Claude Desktop),在 claude_desktop_config.json 中通过 mcp-remote 桥接,参见 MCP 服务器。
用 mcp-remote 桥接 URL,它会打开浏览器登录(OAuth):
npx -y mcp-remote https://app-gatewayv2.imbrace.co/mcpAPI key:
npx -y mcp-remote https://app-gatewayv2.imbrace.co/mcp \ --header "Authorization: Bearer $IMBRACE_API_KEY"完全不用 URL:CLI 可以根据已保存的 profile 运行本地 stdio 服务器 — imbrace mcp。
Web、桌面和移动端的 Claude(自定义连接器)
不使用 Claude Code 时,可以把 iMBrace 作为自定义连接器(custom connector)连接到 Claude——包括 claude.ai、Claude Desktop 和移动应用。这需要网关已启用 OAuth:自定义连接器无法发送 API key。
- 打开 Settings → Connectors,选择 Add custom connector。如果是 Team 或 Enterprise 套餐,需要由 Owner 先在组织的连接器设置中添加,成员再在自己的设置中连接。
- 按环境命名,例如
iMBrace或iMBrace (sandbox),并粘贴选择环境中的 MCP URL。高级设置中的 OAuth client ID 和 secret 留空:Claude 会自行向 iMBrace 注册。 - 选择 Connect,登录 iMBrace,并在授权(consent)页面选择组织和访问权限(读取、写入、删除)。
- 在对话中通过工具菜单启用该连接器,然后提问,例如 “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 时出现 401 | key 错误、已过期、属于其他环境或为空 | 检查 key 和网关主机名 |
403 | 你在该组织中的角色缺少相应权限 | 联系组织管理员 |
402 plan_feature_unavailable(MCP access is not included in your plan) | 该组织的套餐不包含 MCP 访问权限 | 请 iMBrace 管理员为该套餐开启 MCP 访问,或重新 Authenticate 并选择套餐包含 MCP 的组织 |
| 缺少写入或删除类工具,或提示 tool not enabled | OAuth:授权中没有 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 部分。