Agent Toolkit
iMBrace Agent Toolkit 是 iMBrace 官方的 AI 程式碼 agent 外掛。安裝一次,你的 agent 就知道如何在 iMBrace 上建置:TypeScript/Python SDK、託管的 MCP 伺服器、CLI、AI 代理、工作流程、知識庫與 CRM 資料看板。
外掛名稱為 iMBrace Developer,有兩種形式:
- Claude Code — 六個技能加上託管的 iMBrace MCP 伺服器,agent 還能讀取(如果你允許,也能修改)你的 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),請參閱 網頁版、桌面版與行動版的 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。
網頁版、桌面版與行動版的 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 一節。