跳到內容

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-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中的指令。

網頁版、桌面版與行動版的 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 一節。